##########################################################################
######## README for developer ##########
######## FAuST Toolbox ##########
######## Flexible Approximate Multi-Layer Sparse Transform ##########
##########################################################################
##########################################################################
General purpose:
The FAuST toolbox contains a C++ code implementing a general framework
designed to factorize matrices of interest into multiple sparse factors.
It contains a template CPU/GPU C++ code and a Matlab wrapper.
The algorithms implemented here are described in details in [1]- Le Magoarou
For more information on the FAuST Project, please visit the website of the
project: <http://faust.inria.fr>
##########################################################################
[NOTE: Across this doc you'll read in brackets some tmp remarks from Hakim, the current developer on Faust (04/2018)]
##########################################################################
Installation:
Please refer to the document "./gettingStartedFAuST-version2_0.pdf"
##########################################################################
##########################################################################
FAuST structure directory:
./CMake/
--> contains ".cmake" files used to execute some internal cmake
command as to find the path of the externals library, Matlab Path,
Python Path, ...
./externals/
--> contains the externals Library like Eigen, Openblas, ...
./gen_doc/
--> contains both user and developer documentation:
- Developer documentation with Doxygen tool
- User documentation with the getting Started intituled
"gettingStartedFAuST-versionX.pdf" in a LaTeX format in
./gen_doc/LaTeX for
./misc/
--> contains the tests (Ctest tool), the demonstrations, the data,
the configuration files, and the CTest_nightly tools for Continuous
Integration [scripts in CTest_nightly are not used anymore because we rely
on .gitlab-ci.yml script since the project has migrated to gitlab.inria.fr].
./src/
--> contains the C++ sources of the project
./wrapper/
--> contains the wrapper of the project (Matlab, Python, ...)
##########################################################################
##########################################################################
Graphics Processing Unit (GPU): Installation and information
A GPU version of the code is under development, it already shows some time
savings compared to the CPU code for certain computations, but is not
enough user-friendly and not easy to install to be in this release.
The most advanced development is currently on Linux, you can play with it
following the steps described in Section 5.2 of the document
"gettingStartedFAuST-version2_0.pdf".
Report any problem and/or suggestion to the mailing list
http://lists.gforge.inria.fr/pipermail/faust-install/.
INSTALLATION:
As a beta version, the FAµST toolbox integrates optional GPU
(Graphics Processing Unit) acceleration to improve its time performance.
Warning: Currently, this optional GPU install has only be implemented and
tested on a Linux machine. There is no guarantee that the installation and
the use will be effective for every system.
1- Install the CUDA Toolkit from NVIDIA website:
https://developer.nvidia.com/cuda-downloads.
2- Install the drivers for NVIDIA from NVIDIA website:
http://www.nvidia.fr/Download/index.aspx.
3- Verify install of GPU tools by typing in a terminal :
$ which nvcc
You must obtain the path of your nvcc compiler like
$ /usr/local/cuda-7.5/bin/nvcc
If not, add nvcc directory in your environment path (in your /.bashrc file).
4- Verify install of GPU library by typing in a terminal:
$ echo $CUDADIR
You must obtain the path of your cuda directory like
$ /usr/local/cuda-7.5
If not, export CUDADIR (in your /.bashrc file).
export CUDADIR=/usr/local/cuda-7.5
When prerequisities listed in Section 2.1 of the document
"gettingStartedFAuST-version2_0.pdf" are checked, you can get the package FAµST.
1- Download the FAµST package on the website : http://faust.inria.fr/
2- Unzip the FAµST package into your FAµST directory.
3- Open a command terminal
4- Set the current directory to your FAµST directory (NOTE: do not use any special
character in your FAµST directory path, for example the character µ) and type :
$ mkdir build
$ cd build
$ cmake - DBUILD_USE_GPU ="ON" ..
$ make
$ sudo make install # run with administrator privilege
The FAµST Toolbox should be installed. Now, refer to Quick-Start Chapter 4 to check the
install and to try FAµST toolbox using GPU process.
INFORMATION:
When optional parameter BUILD_USE_GPU ="ON" is ON, CPU and GPU processor are used.
CMake files include both ./src/faust_linear_operator/CPU and
./src/faust_linear_operator/GPU files.
Environment variable CUDADIR=/usr/local/cuda-7.5 must be declared in view to find
the following externals GPU library (cf. ./Cmake/findExternalLibs.cmake)
check_external_libraries(cublas CUBLAS_LIB_FILE 1)
check_external_libraries(cudart CUDART_LIB_FILE 1)
check_external_libraries(cusparse CUSPARSE_LIB_FILE 1)
check_external_includes("cublas_v2.h" CUBLAS_V2_INC_DIR 1)
check_external_includes("cusparse.h" CUSPARSE_INC_DIR 1)
check_external_includes("cuda.h" CUDA_INC_DIR 1)
check_external_includes("cuda_runtime_api.h" CUDA_RUNTIME_API_INC_DIR 1)
In case of GPU, the "CUDA" library called FAUST_LINEAR_OPERATOR_GPU_TARGET
is generated contrary to others OBJECT library.
##########################################################################
##########################################################################
Documentation for developer: Doxygen
The Doxygen documentation is available in the following directory:
./gen_doc/
To build Doxygen documentation, build the project with following option:
cmake .. -DBUILD_DOCUMENTATION="ON"
The configuration of Doxygen are defined in the file ./gen_doc/Doxyfile.in
Main page of doxygen is available in following link :
./build/doc/html/index.html
[Specific wrapper API documentation has been added and is also generated through doxygen
when wrapper building cmake variables are set. And more precisely the C++ doxydoc can be excluded if the
cmake variable EXCLUDE_FAUST_LIB_INSTALL is set (this feature is used for release packages).
The documentation is automatically uploaded to gitlab each time a (release) tag is added to the gitlab project.]
##########################################################################
##########################################################################
Website of FAuST project:
To modify and/or update the website of the project FAuST, refer to
following README.txt file :
../website/README.txt
[it's another project in faustgrp (faust's gitlab group): website]
##########################################################################
##########################################################################
Integration Continue:
The Continuous Integration for the project FAUST is based on the CDASH tool
(see. http://www.cdash.org/). The building and test are available on the
public link:
http://cdash.inria.fr/CDash/index.php?project=faust
For more detail concerning C.I. (Virtual Machine, CDash, etc...), refer
to README.txt file in the following directory:
"./devcpp/misc/Ctest_nightly/README.txt"
[this README doesn't apply anymore because we rely on gitlab continuous integration]
[The VMs hosted on cloud stack are associated to the project named faust2 on ci.inria.fr]
##########################################################################
##########################################################################
Create Package of the FAuST toolbox with CPack tool:
CPack tool is used to generate the FAuST Package. CPack is configured in the
principal CMakeList.txt, at the end of the file.
Two types of package can be generated:
- Source package :
* Type following COMMAND in your build directory :
$ cmake ..
$ make package_source
* The FAuST source package is created in your build directory.
* It contains only the sources of the project (all the ./trunk/devcpp
directory, exept the directory defined by the otion :
set(CPACK_SOURCE_IGNORE_FILES "/build/;...).
* This package is working for multiplatform deployment.
- Binaries Packages :
* Type following COMMAND in your build directory :
$ cmake ..
$ make
$ sudo make install
$ sudo make package
* The FAuST binary package is created in your build directory.
* It contains only the files generated by "make install" as library
binarie file...
* This package is dependent to the platform used.
HELP : cf. https://cmake.org/Wiki/CMake:Packaging_With_CPack
[packages generation is made with gitlab continuous integration (.gitlab-ci.yml script).
For macOS cpack isn't used. Packages are saved on gitlab as artefacts associated to commits/relases.]
##########################################################################
##########################################################################
License:
Copyright (2016): Luc Le Magoarou, Remi Gribonval,
Nicolas Bellot, Adrien Leman, Thomas Gautrais
INRIA Rennes, FRANCE
http://www.inria.fr/
The FAuST Toolbox is distributed under the terms of the GNU Affero General
Public License.
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published by
the Free Software Foundation.
This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public
License for more details.
You should have received a copy of the GNU Affero General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.
##########################################################################
##########################################################################
Contacts:
Luc Le Magoarou: luc.le-magoarou@inria.fr
Remi Gribonval : remi.gribonval@inria.fr
Nicolas Bellot : nicolas.bellot@inria.fr
Adrien Leman : adrien.leman@inria.fr
Thomas Gautrais : thomas.gautrais@inria.fr
##########################################################################
##########################################################################
References:
[1] Le Magoarou L. and Gribonval R., "Flexible multi-layer sparse
approximations of matrices and applications", Journal of Selected
Topics in Signal Processing, 2016.
<https://hal.archives-ouvertes.fr/hal-01167948v1>
##########################################################################
##########################################################################
######## README for developer ##########
######## FAuST Toolbox ##########
######## Flexible Approximate Multi-Layer Sparse Transform ##########
##########################################################################
##########################################################################
General purpose:
The FAuST toolbox contains a C++ code implementing a general framework
designed to factorize matrices of interest into multiple sparse factors.
It contains a template CPU/GPU C++ code and a Matlab wrapper.
The algorithms implemented here are described in details in [1]- Le Magoarou
For more information on the FAuST Project, please visit the website of the
project: <http://faust.inria.fr>
##########################################################################
Installation:
https://faust.inria.fr (for pre-built packages) and README.md (for building)
##########################################################################
##########################################################################
FAuST structure directory:
./CMake/
--> contains ".cmake" files used to execute some internal cmake
command as to find the path of the externals library, Matlab Path,
Python Path, ...
./gen_doc/
--> contains both user and developer documentation:
- Developer documentation with Doxygen tool
- User tutorials: jupyter notebooks and matlab live scripts
./misc/
--> contains the tests (Ctest tool), the demonstrations, the data (or a script to download them),
the configuration files, and Continuous
Integration job scripts (used in .gitlab-ci.yml)
./src/
--> contains the C++ sources of the project
./wrapper/
--> contains the wrapper of the project (Matlab, Python)
##########################################################################
##########################################################################
Documentation for developer: Doxygen
The Doxygen documentation is available in the following directory:
./gen_doc/
To build Doxygen documentation, build the project with following option:
cmake .. -DBUILD_DOCUMENTATION="ON"
The configuration of Doxygen are defined in the file ./gen_doc/Doxyfile.in
Main page of doxygen is available in following link :
./build/doc/html/index.html
Specific wrapper API documentation has been added and is also generated through doxygen
when wrapper building cmake variables are set. And more precisely the C++ doxydoc can be excluded if the
cmake variable EXCLUDE_FAUST_LIB_INSTALL is set (this feature is used for release packages).
The documentation is automatically uploaded to gitlab each time a (release) tag is added to the gitlab project.
##########################################################################
##########################################################################
Continuous Integration:
The Continuous Integration for the project FAUST is based on the CDASH tool
(see. http://www.cdash.org/). The building and test are available on the
public link:
https://cdash-ci.inria.fr/CDash/index.php?project=faust
CDash is not so used anymore, the test reports are directly uploaded on gitlab (cf. README-tests-ci-release.md)
For more details concerning CI (Virtual Machines, etc.), refer to ci.inria.fr and cloud stack.
https://ci.inria.fr project faust2
##########################################################################
##########################################################################
References:
[1] Le Magoarou L. and Gribonval R., "Flexible multi-layer sparse
approximations of matrices and applications", Journal of Selected
Topics in Signal Processing, 2016.
<https://hal.archives-ouvertes.fr/hal-01167948v1>
##########################################################################
