This is the README for tsp_cuda.  It contains instructions 
on how to build the program for  MATLAB as well as the 
standalone version.  Instructions are given on how to 
execute the program on sample data. 

The sections to this README include:

A. NOTES FOR MAC USERS
B. PRECOMPILED EXECUTABLES
C. PRIOR TO INSTALLATION
D. BUILDING TSP_CUDA FOR MATLAB
E. BUILDING STANDALONE TSP_CUDA
F. FREQUENTLY ASKED QUESTIONS

****** NOTES FOR MAC USERS *********************

Note to Macintosh users:  you should only compile
and run the software using 32-bit MATLAB.  If 64-bit
MATLAB is installed on your machine, you can 
run 32-bit MATLAB using the command:

matlab -maci

You may also need to define the environment
variable LD_LIBRARY_PATH to give the location of 
the libcudart library. You will do this in the Terminal
before you run Matlab using the command:

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/cuda/lib

Using the correct path for your system.

****** PRECOMPILED EXECUTABLES ****************

The MATLAB implementation of tsp_cuda is available for all
operating systems with a MATLAB installation (Linux, Mac, Windows).
MATLAB MEX files will need to be compiled for your system before
you can run it.  The compilation process is automated and requires
the CUDA development drivers and Toolkit installed on your system.
Detailed compilation instructions are below.

This package also includes source code and precompiled executables
for a command-line tsp_cuda that does not require MATLAB.  Precompiled 
executables for cuda_tsp are provided in the tsp/example directory.  
Executables are provided for Linux and Mac OSX.  Windows users will 
need to compile the software for their system.  Instructions for 
compiling the software for all operating systems are below. Due to 
variations in GPU architectures and continuously updating CUDA 
drivers, we recommend that all users recompile the executables
for their specific system.

****** PRIOR TO INSTALLATION *******************

Prior to installing either the MATLAB or standalone version of 
this software, you must:
1. Have an NVIDIA GPU with the CUDA architecture installed in your machine.  
2. Have installed the NVIDIA developer drivers and CUDA Toolkit for 
your system.  The most recent drivers and toolkit can be found here:
http://developer.nvidia.com/object/cuda_3_2_toolkit_rc.html
 
3.  Once you install the toolkit you will have a new compiler on your
system, the NVCC compiler, which compiles kernel code for the GPU.
You will also have the CUDA libraries and include directories installed.

On Linux and Mac OSX these directories are typically:
/usr/local/cuda/bin (for the compiler itself)
/usr/local/cuda/include
/usr/local/cuda/lib (32 bit systems)
/usr/local/cuda/lib64 (64 bit systems)

On Windows, these are typically
C:\CUDA\bin (for the compiler itself)
C:\CUDA\include
C:\CUDA\lib (32 bit systems)
C:\CUDA\lib64 (64 bit systems)

4.  You will also need a C++ compiler on your system. Linux and 
Mac OSX users probably have gcc already.  Windows users will need 
Visual Studio to compile. Instructions
 
******  BUILDING TSP_CUDA FOR MATLAB *********************

1.  The directory tsp_cuda/matlab contains the source code for the MATLAB
implementation.  To begin, you want to edit the file 'make.m' to customize
the build for your system.  The defaults may just work, but you should 
check to make sure.  Open the file 'make.m' in a text editor. You will see
the following:

if ispc % Windows
    CUDA_Compiler_Location = 'C:\CUDA\bin\nvcc';
    CUDA_LIB_Location = 'C:\CUDA\lib';
    Host_Compiler_Location = '-ccbin "C:\Program Files\Microsoft Visual Studio 9.0\VC\bin"';
    PIC_Option = '--gpu-architecture compute_11 --gpu-code sm_11,sm_12,sm_13,sm_20 ';
else % Mac and Linux (assuming gcc is on the path)
    CUDA_Compiler_Location = '/usr/local/cuda/bin/nvcc';
    CUDA_LIB_Location = '/usr/local/cuda/lib64/';
    Host_Compiler_Location = '';
    PIC_Option = '--gpu-architecture compute_11 --gpu-code sm_11,sm_12,sm_13,sm_20  --compiler-options -fPIC ';
end

You will want to edit these paths to match the settings on your system.
The directories should be similar to those discussed in the "Prior
to installation" section above. Note that the software is compiled
to run on GPUs of compute capability 1.1, 1.2, 1.3, and 2.0.
This software will run on machine of compute capability 1.1 and higher.  

2.  Open MATLAB in this directory tsp_cuda/matlab, and type 'make' to 
build the installation. Warnings about source files and 32-bit compatibility 
are normal.

3.  To test the installation, move into the tsp_cuda/example directory
and run 'TestMatlab'.  This file contains instructions for testing 
all the algorithms (TSP, kTSP, and TST) using filtering for differential
expression, probe names, and cross validation.  If all of the tests
run correctly, tsp_cuda is working properly! Examples for using MATLAB
to run all the algorithms under different conditions can be found in the 
file TestMatlab.m.  The test data are provided in the files GIST_LMS_small.csv
(with probe names as row headers), and GIST_LMS_small_norow.csv (no probe names).    

******  BUILDING STANDALONE TSP_CUDA *********************

1.  The directory tsp_cuda/standalone contains the source code and 
Makefile for the standalone version of tsp_cuda.  Before trying to 
build the software, open the file 'Makefile' in a text editor
to edit the settings specifically for your system. You will 
see the following:

# Location of the NVCC compiler for your machine
NVCC := /usr/local/cuda/bin/nvcc

# Location of the NVCC include directory for your machine
CUDA_INCLUDE_DIR := -I/usr/local/cuda/include

# Location of the NVCC lib directory for your machine
CUDA_LIB_DIR := -L/usr/local/cuda/lib64

# Fermi architecture: compute_20 and sm_20
# Tesla architecture: compute_1X and sm_1X where X is 1,2,or 3
GPU_ARCH := --gpu-architecture compute_11
GPU_CODE := --gpu-code sm_11,sm_12,sm_13,sm_20

You will want to edit these paths to match the settings on your system.
The directories should be similar to those discussed in the "Prior
to installation" section above. Note that the software is compiled 
to run on GPUs of compute capability 1.1, 1.2, 1.3, and 2.0.  
This software will run on machine of compute capability 1.1 and higher.  

2.  Run 'make' to build the installation.  The executable 'tsp_cuda' will
be built in the 'build' directory.  You can test this executable using
the data in the tsp/example directory.  Here are some sample commands:

# Run top-scoring pair on the sample data, no filtering
tsp_cuda GIST_LMS_small_norow.csv tsp

# Run top-scoring pair on the sample data, no filtering, ouput to file 'output'
tsp_cuda GIST_LMS_small_norow.csv tsp -o output

# Run top-scoring pair filtering for top 500 differentially expressed genes, 
tsp_cuda GIST_LMS_small_norow.csv tsp -N 500

# Run top-scoring pair with probe names in the first column of the input file
tsp_cuda GIST_LMS_small.csv tsp -p

# Run top-scoring triple with any of the settings used before
tsp_cuda GIST_LMS_small.csv tst [-p -N 500 -o output]

Simply running tsp_cuda with no command line options will print a list of 
possible options to the program and instructions on what they mean.

If you have any questions, please contact Andrew Magis at magis1@illinois.edu.

****** FREQUENTLY ASKED QUESTIONS *****************************

Q1:  When I try to run the standalone executable on my machine, I get
the error: 'error while loading shared libraries: libcudart.so.3: cannot open shared object file: No such file or directory'

A1:  The executable is compiled with a library called 'cudart', which is
part of the NVIDIA CUDA Toolkit.  The executable needs to know where this 
library resides on your system.  Make sure the environment variable
'LD_LIBRARY_PATH' includes the path to this library for your system.  The
path on Linux or Mac OSX will likely be one of the following:
/usr/local/cuda/lib
/usr/local/cuda/lib64
The path for Windows will likely be:
C:\CUDA\lib

Q2:  When I try to run cuda_tsp for MATLAB on a Mac, I get an error about @rpath and the libcudart library.

A2:  MATLAB cannot find the cudart library, which is required to run the compiled CUDA code.  It is installed to your system as part of the NVIDIA CUDA toolkit.When MATLAB starts, it reads the environment variable 'LD_LIBRARY_PATH' to 
get paths to libraries.  You need to add the path to the cudart library to 
this environment variable before you start MATLAB from the terminal.  To do so
execute the following commands in the Terminal:

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/cuda/lib
matlab -maci

The first command sets the LD_LIBRARY_PATH environment variable (change the path
to that which is appropriate for your system), and the second runs 32-bit MATLAB,
which is required. 
