BaderLab / ecuda

                  ecuda Extended CUDA C++ API release 2.x

These are the release notes for ecuda version 2.

WHAT IS ECUDA?

  ecuda is a C++ wrapper around the CUDA C API designed to closely resemble and
  be functionally equivalent to the C++ Standard Template Library (STL).
  Specifically: algorithms, containers, and iterators. These elements play nice
  with host containers and can be used in device code.

EXAMPLE

  This is a simple example of how some elements of ecuda look in practice.

  std::vector<double> hostVector( 1000 );
  ecuda::vector<double> deviceVector( hostVector.begin(), hostVector.end() );
  CUDA_CALL_KERNEL_AND_WAIT( squareRoot<<<1,1000>>>( deviceVector ) );
  ecuda::copy( deviceVector.begin(), deviceVector.end(), hostVector.begin() );

  __global__
  void squareRoot( typename ecuda::vector<double>::kernel_argument vec )
  {
    const int t = threadIdx.x;
    vec[t] = sqrt(vec[t]);
  }

  More detailed examples can be found in the full documentation.

REQUIREMENTS

  ecuda is a header only API, and the only pre-requisite library is the CUDA API
  version 5 or later. It should work with any C++ compiler, but has been
  developed and tested with several versions of gcc (most recently 4.8.4) and
  clang 3.6. The C++11 standard is optional, but is utilized if enabled. Visual
  Studio 2013 on Windows 10 was also successfully tested (see the INSTALLATION
  section below).

  A correct setup should be able to compile the tools/print_device_info.cu
  program without issue. You can try:

    $ mkdir bin
    $ cd bin
    $ cmake ../tools
    $ make

  to identify any issues. When run, the program prints out a pretty summary of
  the current system's GPU hardware and capabilities.

DOCUMENTATION:

 - Documentation can be viewed online:

     https://baderlab.github.io/ecuda/

 - This is generated from the source files themselves using doxygen. The base
   directory contains a default doxygen.cfg file that will build a local copy of
   the documentation in the docs/html subdirectory. Make sure you have doxygen
   installed and run:

     $ doxygen doxygen.cfg

INSTALLATION:

  Linux/MacOS:

  - As long as the include/ subdirectory is visible to the compiler, the API
    can be installed anywhere. A default install using cmake can be done by
    running:

      $ cmake .
      $ sudo make install

    This will copy the contents of the include/ subdirectory to
    ${CMAKE_INSTALL_PREFIX}/include (usually /usr/local/include).

  Windows/Visual Studio:

   - The latest free Visual Studio at the time of last update was Visual
     Studio Community 2015, but it is confirmed that CUDA 7.5 is not supported
     at this time. I managed to get everything working with Visual Studio
     Community 2013 on Windows 10. Here is my story:

   - Download and install Visual Studio Community 2013 from:

       https://www.visualstudio.com/en-us/news/vs2013-community-vs.aspx

   - Download and install the Nvidia CUDA Toolkit from:

       http://developer.nvidia.com/cuda-downloads

     - The order is important since the CUDA installer integrates with any
       installed Visual Studio versions that it supports. Also note that in the
       successful configuration, only the following items in the CUDA
       installer's custom installation were left checked:

         CUDA Toolkit 7.5
         CUDA Visual Studio Integration 7.5

       The following items were already installed on the test system with equal
       or greater version numbers:

         Graphics Driver
         HD Audio Driver
         NVIDIA GeForce Experience
         PhysX System Software

       Do whatever makes the most sense for your situation.

   - Start Visual Studio and load the ecuda.sln solution file.

   - The print_device_info project contains a source file that should build
     successfully at this point. Build the Release target with the x64
     platform, and bin/x64/Release/print_device_info.exe should appear. Running
     this from the Windows command line should display a pretty summary of the
     current system's GPU hardware and capabilities.

   - When building a Debug target, Visual Studio's C++ Standard Library
     implementation does some kind of "iterator checking" that doesn't play
     nice with ecuda's custom iterators, causing erroneous assertion failures
     to get raised at runtime. Placing this at the beginning of a program will
     turn this off (and suppresses a warning about macro redefinition):

       #pragma warning(disable:4005)
       #undef _HAS_ITERATOR_DEBUGGING
       #pragma warning(default:4005)

   - Since ecuda is not actively developed on Windows, please report any issues
     or workarounds!

BENCHMARKS AND EXAMPLES:

  - The benchmarks/, test/ and t/ directories contain programs that were useful
    for development. They might be useful examples to see how ecuda can be used.
    Again, these were used during API development so they can be quite ugly and
    full of hacks.

  - Each subdirectory contains a CMakeList.txt file so building them should be
    easy if your system is properly set up. For example, to build the
    benchmarks/ folder, the following could be used:

      $ mkdir -p bin/benchmarks
      $ cd bin/benchmarks
      $ cmake ../../benchmarks
      $ make

  - Note that a file called local-config.cmake can be created in the release
    root directory that contains any system-specific CMake directives (e.g.
    nvcc compiler flags). The local-config.cmake.example file is an example of
    how this file might look.

FILE DESCRIPTIONS:

  benchmarks/                Programs that compare cuda and ecuda performance.
  docs/                      Additional elements for building docs with doxygen.
  include/                   The ecuda API header files.
  t/                         Catch unit tests.
  test/                      Programs to loosely test elements of the API.
  tools/                     Utilities that utilize ecuda.
  CMakeLists.txt             CMake configuration file
  doxygen.cfg                doxygen configuration file
  ecuda.config               Qt Creator project file
  ecuda.creator              Qt Creator project file
  ecuda.files                Qt Creator project file
  ecuda.includes             Qt Creator project file
  ecuda.sln                  Visual Studio 2013 Solution file
  local-config.cmake.example Example file with additional CMake directives
  .gitignore                 local files to omit from version control
  LICENSE.txt                release license
  MANIFEST                   list of files under version control
  README                     this file
  VERSION                    current version of the API