Minor changes.

Refresh a little bit READMEs and old todo list (not up to date with all new todos, just added remarks or done checks). Fix typo. in filename TODOLIST.developper.

Minor changes.
1029faaf · hhakim · cd539411 · 1029faaf · 1029faaf · 1029faaf
Commit 1029faaf authored 6 years ago by hhakim
--- a/README.developer
+++ b/README.developer
-##########################################################################
########                 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:

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. 
./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
##########################################################################


##########################################################################
Website of FAuST project: 

To modify and/or update the website of the project FAuST, refer to 
following README.txt file : 
../website/README.txt
##########################################################################


##########################################################################
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"
##########################################################################


##########################################################################
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
##########################################################################


##########################################################################
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>
##########################################################################	
\ No newline at end of file
+##########################################################################
########                 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>
##########################################################################	
\ No newline at end of file

--- a/README.md
+++ b/README.md
@@ -10,6 +10,7 @@ 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.
+A Python wrapper is also available.
 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
@@ -23,7 +24,7 @@ Installation
 Please refer to the document "./gettingStartedFAuST-version2_0.pdf"
 to install the FAUST toolbox.
 The FAUST toolbox has been tested on the following environments:
- LINUX (fedora 20, 21, 22, 23 / Ubuntu)
+- LINUX (fedora 20, 21, 22, 23, 24 - 27 / Ubuntu)
 - MACOS X
 - WINDOWS (windows 7)

@@ -72,11 +73,19 @@ along with this program.  If not, see [licenses](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
+
+	Rémi Gribonval: remi.gribonval@inria.fr
+	Hakim: hakim.hadj-djilani@inria.fr
+	
+
+Credits
+========
+	Luc Le Magoarou
+	Remi Gribonval
+	Nicolas Bellot
+	Adrien Leman
+	Thomas Gautrais
+	Hakim H.
 ---

 References

--- a/TODOLIST.developper
+++ b/TODOLIST.developper
@@ -19,6 +19,7 @@ project: <http://faust.inria.fr>

 This file presents the current state of the FAuST toolbox on the svn repository
 and what could be made by future developper.
+[Across this doc you'll read in brackets some tmp remarks from Hakim, the current developer on Faust (04/2018)]


 Here are the different topics presented in this documents :
@@ -78,6 +79,10 @@ The C++ code is split in 2 part :
 		|->	-Transform : class inherits from LinearOperator and represents the Flexible Approximate Multi-layer Sparse Transform,
 		|	 it is a list of MatGeneric (std::vector<MatGeneric*>) representing its factors.Currently, a factor of a Faust can be
 		|	 sparse matrix or a dense matrix.
+
+		|[-> TransformHelper class was added to wrap Transform class and ease the use of Transform objects from wrappers, 
+			especially to enhance memory management for different Faust/Must objects relying on the same background Transform object (typically for a Faust and its tranpose, etc.). 
+			See commit c775e359 for further details (Hakim)]
 			
 		

@@ -96,7 +101,7 @@ The C++ code is split in 2 part :
 		     
 		     - The compatibility with complex scalar is ok.
 		       Currently, you can multiply the transposed of a Trasnform by a MatDense.
-		       But it could be interesting to multiply by the conjugate or the transconjugate of a Transform.
+		       But it could be interesting to multiply by the conjugate or the transconjugate of a Transform [Hakim: it's done for TransformHelper class used in wrappers, so it's ok].

 		     - WARNING :  the GPU matrices are not well tested ... and no documentation is available on the structure of the code...

@@ -163,7 +168,7 @@ II - Wrappers            :
 	 **** TODO **** :
 	 --> Make the Faust Matlab class operation conjugate and transconjugate are not implemented.
 	     So, it will be easy to make, this operation implementation should be very similar to 
-	     the transpose implementation. 
+	     the transpose implementation.[DONE (Hakim)] 
 	--> Make the Matlab factorization algorithm compatible with complex matrices and GPU matrices.


@@ -173,7 +178,7 @@ II - Wrappers            :
 	  It supplies : 
          --> the FaustPy Python module.
 	      This module supplies the Faust class wich is the equivalent of the C++ class Transform.	 
-	      It is only compatible with real scalar.
+	      It is only compatible with real scalar [Not anymore, now complex scalar are supported (Hakim)].
 	  
 		 

@@ -181,7 +186,7 @@ II - Wrappers            :
 	  

 	 **** TODO **** :
-	 --> Make the FaustPy.faust class compatible with complex scalar.
+	 --> Make the FaustPy.faust class compatible with complex scalar [DONE (Hakim)].
 	 --> Develop the inferface with the factoziration algorithm.
 	 --> Implements some Python demos similar to the Matlab Demo (Brain Source localization ...)		 

@@ -201,6 +206,9 @@ III - TEST             :
 	III-1) test with CTest
 		all the test are defined in the directory misc/test/.
 		(For more information on this, see misc/test/README.developper) 
+		[The script tests located in misc/CTest_nightly directory are not relevent anymore because since the gitlab migration
+		of the project we rely on gitlab continuous integration and use .gitlab-ci.yml script to launch tests, 
+		but cdash and ci.inria.fr are still used (Hakim)]
 	
 	III-2) test with CDash on VM
 	       Daily, all the test are launched on virtual machine
@@ -222,6 +230,7 @@ III - TEST             :

 			- Windows : all the test on Windows VM currently won't work...
 			  	There are problem into the step of CMake configuration.
+				[Some progress have been made to make windows version build and run (Hakim)]