-----------------------------------------------------------------
-------- GURLS - Grand Unified Regularized Least Squares --------
-----------------------------------------------------------------


Table of Contents
=================

- Introduction
- Installation
   - Dependencies
   - Automatic dependencies building
   - Installing GURLS++ on Linux
   - Installing GURLS++ on Windows
   - Configuration
- Documentation

Introduction
===========

bGURLS++ - ((big) Grand Unified Regularized Least Squares) is a C++ software package
for training linear multiclass classifiers based on the Regularized Least Squares
(RLS) loss function in the Big Learning Scenario.


Installation
============
 
1) Dependencies
---------------

bGURLS++ depends on several external libraries:

- A Blas/Lapack implementation. Currently we support:
  - AMD’s ACML (only for 64 bits);
  - ATLAS;
  - Intel’s MKL;
  - Netlib’s reference implementation: http://www.netlib.org/blas and http://www.netlib.org/lapack/;
  - OpenBLAS (Currently only under Linux);
  - Boost’s (v1.46.0 or higher) libraries serialization, date_time, filesystem, 
    unit_test_framework, system, signals.
  - MPI. BGURLS++ has been successfully tested with MPICH http://www.mpich.org/;
  - Zlib http://www.mpich.org/;
  - LibHDF5 v1.8.9 http://www.hdfgroup.org/HDF5/ compiled enabling parallel support and zlib 
    (Libhdf5 v1.8.10 or higher is proved to not work properly);

2) Automatic dependencies building
----------------------------------

The bGURLS++ CMake configurator supports automatic downloading and building 
of all dependencies by setting the GURLS_USE_EXTERNAL_* variables to ON (See section 
Configuration below for details). 

3) Installing bGURLS++ on Linux
-------------------------------

Below we describe how to build and install bGURLS++ on Ubuntu (tested on Ubuntu 12.04). 
For other distributions, the same packages must be installed with the distribution-specific method.

1. Install the cmake build system (www.cmake.org/)
 
 $ sudo apt-get install cmake cmake-curses-gui
 
2. To link against some Blas and Lapack implementations you may need a fortran compiler e.g. for gfortran:

 $ sudo apt-get install gfortran

3. Create a build directory (e.g. "build") for GURLS++

 $ cd $GURLS_ROOT
 $ mkdir build
 
4. Run cmake into the build directory

 $ cd build
 $ ccmake ..

The last command will show the CMake interface, which must be used to set the values of some variables 
used for building and installing bGURLS++. See the section Configuration below for more information on 
these variables and how to set them to appropriate values.

5. Start building

 $ make

6. Install the library to the path defined at configuration time

 $ make install

The command wil also install to the same path all the dependencies that user chose to build automatically.

4) Installing bGURLS++ on Windows
--------------------------------

Below we describe how to build and install GURLS++ on Windows with Visual Studio (tested with 
VS Express 2010 and 2012).

1. Install the CMake build system downloading the installer from http://cmake.org/cmake/resources/software.html.

2. Create a build directory (e.g. $GURLSROOT/build).


3. Run the CMake GUI. You will have to set the source directory to $GURLSROOT directory, and the build
   directory to the directory created at the previous step. After pressing the configure button, 
   you will have to chose the generator for the project (e.g. Visual Studio 10). 
   On Windows you may encounter the error message "error in configuration process, 
   project files may be invalid", check that the you have writing rights to the path specified 
   in the variable CMAKE_INSTALL_PREFIX. If this is not the case, change such a variable
   to a folder to which you have writing rights and press 'configure'. 
   Now you have to set the values of some variables used for building and installing the 
   libraries according to your preferences. See the section Configuration below for more information
   on these variables and how to set them to appropriate values. 
   After having configured the build options, press the generate button to create the solution file.

4. Open the generated solution under Visual Studio and build it.

5. If you used external Blas-Lapack, the Openblas DLLs will be automatically copied in the 
	"$GURLSROOT/build/bin" folder, please add it to your path to run executables.

6. Optional: install bGURLS++ by explicitly building the install project included in the solution 
  (it is not automatically built when building the solution).


5) Configuring bGURLS++
----------------------

The configuration step is carried out using CMake. In the following we describe the configuration process 
using the GUI of CMake, e.g. under Windows or Mac. A similar process shall be followed when using the 
command-line interface.

1. Press 'configure', and CMake will try to determine the correct values for all variables. 

2. After the first configuration a list of variables is displayed. The following variables should be checked:
    - CMAKE_INSTALL_PREFIX The path where the library will be installed to;
    - GURLS_BUILD_GURLSPP (ON): Build GURLS++. If set to ON CMake also evaluates the variables
    - GURLSPP_BUILD_DEMO (ON): Enable the building of the GURLS++ demo programs;
    - GURLSPP_BUILD_DOC (OFF): Enable the building of the GURLS++documentation using doxygen;
    - GURLS_BUILD_BGURLSPP (ON): Build bGURLS++. If set to ON CMake also evaluates the variables
    - BGURLSPP_BUILD_DEMO (OFF): Enable the building of the BGURLS++demo programs;
    - BGURLSPP_BUILD_DOC (OFF): Enable the building of the BGURLS++documentation using doxygen;
    - GURLS_USE_BINARY_ARCHIVES (ON): If set to ON, all data structures are stored in binary 
	 (rather than text) files, saving storage space and time;
    - GURLS_USE_EXTERNAL_BLAS_LAPACK (ON): Enable automatic building of Blas and Lapack, using OpenBLAS,
   	  under linux, or automatic linking to the provided OpenBLAS pre-built libraries, under windows.
    - GURLS_USE_EXTERNAL_BOOST (ON): Enable automatic building of boost. If set to OFF, press 'advanced' 
      to visualize the variables related to the BOOST library, typically you have to specify only the 
      variable BOOST_INCLUDE_DIR;
    - GURLS_USE_EXTERNAL_HDF5 (ON): Enable automatic building of libHDF5 and its dependencies 
	  (MPICH and zlib). Used only if GURLS_BUILD_BGURLSPP is set to ON.

		
3. For each variable GURLS_USE_EXTERNAL_* which is set to OFF, you must specify the path
   to the corresponding library. If CMake does not find some required library, an error 
   message will be displayed. Change the path to required library and press 'configure' again.
   
4. In the main screen you may change a number of variables. Most of them can be left unchanged, but some 
   must be set to appropriate values. The following are the variables whose values should be checked:
    - BLAS_LAPACK_IMPLEMENTATION. Allows user to specify an implementation of the Blas/Lapack routines. 
      Available choices are: ACML, ATLAS, MKL, NETLIB, OPENBLAS. Depending on the choice you make, 
      CMake will try to find the libraries in standard locations in the system. 
	  Normally this process should run fine, however, in case the libraries have been installed 
	  in some non-standard directory, you may have to manually specify their location.
      
5. Once all variables have been set, press 'configure' again, and CMake will check the settings. 
   As in step (3), if something is wrong an error message will be displayed and you will have 
   to go back to the main screen to tweak the configuration.

6. When the settings are correct, the option ’generate’ will appear. Press 'generate'. 
   CMake will generate the files and exit.

After the build files (e.g. the Makefile under Linux) have been generated, you can proceed as explained above.


Documentation
=============

- Quick intructions on how to run the libraries for a default case can be found here: 
	https://github.com/CBCL/GURLS/wiki/2-Getting-Started#wiki-Hello_World_in_bGURLS-2

- A User manual with several examples can be found here:
	https://github.com/CBCL/GURLS/wiki/3-User-Manual#wiki-bGURLS_Usage-2

- C++ Code Documentation can be found at: http://cbcl.github.io/GURLS/

- Further documentation	
	* Description of the available methods, demos and data for each package can be found at
		https://github.com/CBCL/GURLS/wiki/4-Code-Description#wiki-bGURLS-2

	* In gurls-manual.pdf you can find both the installation instructions and user manual, 
      together with the Developer's Guide. GURLS is designed for easy expansion. Give it a try!
	  Remark: GURLS++ is still under development please contact the authors before starting 
	  your own development.