doc gettingStartedFAuST-version2_1 + wrapper python doc

gen_doc/LaTeX/chapIntroduction.tex

@@ -31,7 +31,7 @@ Chapter \ref{sec:firstUse} shows quickly how to use this library and gives an ex
 
 \begin{figure}[H] %%[!htbp]
 \centering
-\includegraphics[scale=0.4]{images/recapInstall.pdf}
+\includegraphics[scale=0.4]{images/recapInstall_v2-1.pdf}
 \caption{Tested configurations: Platforms and IDE}
 \label{fig:recapInstall}
 \end{figure}
@@ -42,13 +42,13 @@ A brief outline of the code structure and status is given on Figure~\ref{fig:fau
 \item the "FA$\mu$ST matrix multiplication" provides efficient linear operators to efficiently manipulate your data, relying on efficient low-level routines from external libraries where needed; 
 \item the "Factorization algorithms" is used to generate a FA$\mu$ST core from a dense matrix. 
 \end{itemize}
-Various wrappers are planned to call \textrm{libfaust}. In the current version of \FAuST\ (Version 2.0), only the Matlab wrapper is implemented. Command-line, Python and A||GO wrapper are planned in the next version of FA$\mu$ST (see Section \ref{sec:WorkingProgress}).   
+Various wrappers are planned to call \textrm{libfaust}. In the current version of \FAuST\ (Version 2.1), only the Matlab wrapper and the Python wrapper is implemented. Command-line and A||GO wrapper are planned for the next version of FA$\mu$ST (see Section \ref{sec:WorkingProgress}).   
 
 
 \begin{figure}[H] %%[!htbp]
 \centering
-\includegraphics[scale=0.45,trim = 0cm 3cm 0cm 3cm, clip]{images/FaustStructure.pdf}
-\caption{Brief structure of FA$\mu$ST version 2.0.0}
+\includegraphics[scale=0.45,trim = 0cm 3cm 0cm 3cm, clip]{images/FaustStructure2-1.pdf}
+\caption{Brief structure of FA$\mu$ST version 2.1.0}
 \label{fig:faustStructure}
 \end{figure}
 
@@ -67,3 +67,25 @@ Various wrappers are planned to call \textrm{libfaust}. In the current version o
 
 \paragraph{License :}Copyright (2016) Luc Le Magoarou, Remi Gribonval INRIA Rennes, FRANCE \\
 The FA$\mu$ST 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 \url{http://www.gnu.org/licenses/}.
+
+
+\section{New Features since last version}\label{sec: RequiredTools}
+
+Here are presented somes new features that are incorporated in the current version (2.1) and weren't available in the former version.
+
+\paragraph{Python wrapper}
+The a beta version of the Python wrapper is now available.
+The list of components you musthave to use this wrapper is defined in the following section (\ref{sec:Pythonwrapper}).
+
+
+
+\paragraph{Matlab wrapper : complex scalar compatibility}
+The Matlab wrapper is now compatible with complex scalar.
+This allows you to construct Faust from complex factors
+and multiply with complex matrices.
+Nevertheless, the transconjugate and conjugate operation are not yet implemented. 
+
+\paragraph{C++ code : improvement}
+Some improvement have been made to improve the speed-up of a Faust. For instance, a factor of a Faust is no longer necessarily a sparse matrix.Now, it's a  now generic matrix.
+This means that currently it can be a full-storage matrix or sparse one. The choice of the format that will represent the factor is made at execution time for more flexibility.
+Another advantage, this for future development, the class/interface of generic matrices can be inherited/implemented by more specific format (block-diagonal matrices, permutation matrices) or more efficient. 
\ No newline at end of file

gen_doc/LaTeX/chapWorkingProgress.tex

@@ -17,6 +17,143 @@ some time savings compared to the CPU code for certain computations, but is not
 This experiment was in the previous release (FA$\mu$ST version 1.0, pure Matlab implementation) but is not in the current one because our C++ wrapper is not yet compatible with the sparse decomposition algorithm used in this experiment. Please use version 1.0.0 to reproduce this image denoising experiment. 
 \end{itemize}
 
+\section{Python wrapper : beta version}\label{sec:Pythonwrapper}
+This section describes the different step to install the Python wrapper and to get acustomed to its behaviour.
+The Python wrapper has only been tested on Unix system, not Windows.
+
+Throughout this section we provide examples as follows:
+\begin{itemize}
+\item Command lines you must enter in a terminal are displayed as:
+\lstset{style=customBash}
+\begin{lstlisting}
+> mkdir BUILD; ls . 
+\end{lstlisting}
+\item Messages resulting from such command lines appear without the leading '>':
+\lstset{style=customBash}
+\begin{lstlisting}
+example of return text in your current terminal. 
+\end{lstlisting}
+\item Python code is displayed like this :
+\lstset{style=customPython}
+\begin{lstlisting}
+# this is a commentary
+y = A*x; 
+\end{lstlisting}
+\end{itemize}
+
+\subsection{Required Components}
+This Section lists the required components you must install before to begin the FA$\mu$ST installation.
+
+\begin{itemize}
+\item \textbf{Install Python}. The wrapper has only been tested with Python version 2 (2.7.x) (\url{https://cmake.org/download/}).
+To install Python 2, type the following command :
+\lstset{style=customBash}
+\begin{lstlisting}
+> pip install python2
+\end{lstlisting}
+But Python 2 is a native package on many Unix system.
+ 
+\item \textbf{Install Numpy}
+Numpy is a Python package useful linear algebra (http://www.numpy.org/)
+It is often delivered with Python but in case you haven't it,you can install it by typing the following command :
+\lstset{style=customBash}
+\begin{lstlisting}
+> pip install numpy
+\end{lstlisting}
+
+Check the version of the Numpy package,
+by typing the following command :
+\lstset{style=customBash}
+\begin{lstlisting}
+> pip freeze | grep 'numpy'
+\end{lstlisting}
+
+\textbf{Warning} : version of Numpy older than 1.9.2 may be not compatible with the Python wrapper
+ 
+\item \textbf{Install Cython}
+Cython is a Python package, that allows to interface C/C++ with Python. (\url{http://cython.org/})
+
+It is often delivered with Python but in case you haven't it,you can install it by typing the following command :
+\lstset{style=customBash}
+\begin{lstlisting}
+> pip install cython
+\end{lstlisting}
+
+\end{itemize}
+
+
+
+\subsection{Install}
+The installation is very similar to the installation of the Matlab wrapper. 
+
+
+\begin{itemize}
+\item \textbf{Type the following commands :} 
+\lstset{style=customBash}
+\begin{lstlisting}
+> mkdir build
+> cd build
+> cmake .. -DBUILD_WRAPPER_PYTHON=ON 
+> make
+> sudo make install # run with administrator privilege
+\end{lstlisting}
+
+
+\item By default,
+The Python wrapper is installed in the directory : \texttt{<HOMEDIR>\textbackslash Documents\textbackslash PYTHON\textbackslash faust}.
+
+But you can choose your own install directory by setting the \newline
+CMAKE variable  \textbf{CMAKE\_INSTALL\_PYTHON\_PREFIX}.
+
+
+
+Type the following command :
+ \lstset{style=customBash}
+\begin{lstlisting}
+> mkdir build
+> cd build
+> cmake .. -DBUILD_WRAPPER_PYTHON=ON -DCMAKE_INTALL_PYTHON_PREFIX="YourPath" 
+> make
+> sudo make install # run with administrator privilege
+\end{lstlisting}
+
+\end{itemize}
+
+
+
+\subsection{Quickstart}
+	This subsection presents the quickstart demo to get acustomed to the Python wrapper.
+	 Now, you can go to the install directory of the Python wrapper which is \newline \texttt{<HOMEDIR>\textbackslash Documents\textbackslash PYTHON\textbackslash faust} by default.
+	\newline
+	
+	\begin{itemize}	
+	\item In a terminal, type the following command :
+	 \lstset{style=customBash}
+	\begin{lstlisting}
+	> cd ~/Documents/PYTHON/faust/
+	\end{lstlisting}
+	\item You can run the Python script \texttt{quickstart.py}
+	by typing the following command :
+	\lstset{style=customBash}
+	\begin{lstlisting}
+	> python quickstart.py
+	\end{lstlisting}
+	\end{itemize}
+	
+	In this script
+	\begin{enumerate}
+		\item We import the FaustPy package
+		\lstinputlisting[firstline=39,lastline=40,style=customPython]{../../wrapper/python/quickstart.py}
+		\item We create a Faust from a list of factors represented as Numpy matrices
+		\lstinputlisting[firstline=64,lastline=65,style=customPython]{../../wrapper/python/quickstart.py}
+		\item A list of overloaded Numpy operation shows that a Faust is handled as a normal
+			  Numpy matrix.
+		\lstinputlisting[firstline=67,lastline=83,style=customPython]{../../wrapper/python/quickstart.py}
+		\item It performs a little time comparison between multiplication by a FA$\mu$ST or its Numpy equivalent matrix.
+		\lstinputlisting[firstline=67,lastline=83,style=customPython]{../../wrapper/python/quickstart.py}	  
+	\end{enumerate}
+		
+	
 \section{Construct a FAuST from a given matrix}\label{sec:WorkingProgressBuildFromMatrix}
 Please ensure that you have configured your Matlab environment (cf. Section \ref{sec:firstUseMatlabPath}). Then, to see an example of building a FA$\mu$ST from a matrix, you can run \texttt{factorize\_matrix.m} in the Matlab Command Window by typing :
 \lstset{style=customMatlab}

gen_doc/LaTeX/gettingStartedFAuST-version2_0.tex → gen_doc/LaTeX/gettingStartedFAuST-version2_1.tex

 \documentclass[a4paper,11pt]{report}
 \author{Adrien Leman; Nicolas Bellot}
 \def \FAuST {FA$\mu$ST}
-\title{Getting Started with the FA$\mu$ST Toolbox \smallbreak "Flexible Approximate Multi-Layer Sparse Transforms" \bigbreak
+\title{Getting Started with the FA$\mu$ST Toolbox version 2.1 \smallbreak "Flexible Approximate Multi-Layer Sparse Transforms " \bigbreak
 \bigbreak
 \centerline{\includegraphics[scale=0.1]{images/logo.png}}
 }
@@ -56,6 +56,8 @@
 
 \definecolor{mygray}{rgb}{0.95,0.95,1}
 \definecolor{mygrayMatlab}{rgb}{0.9,0.9,0.9}
+\definecolor{pythonColor}{rgb}{0.5,0.5,0.5}
+\definecolor{pythonCommentColor}{rgb}{0.1,0.3,0.1}
 \definecolor{mymauve}{rgb}{0.58,0,0.82}
 \definecolor{myBlack}{rgb}{0.3,0.3,0.3}
 
@@ -121,6 +123,29 @@
     %emph=[2]{word1,word2}, emphstyle=[2]{style},  
 }
 
+\lstdefinestyle{customPython}{
+	language=Python,% 
+	backgroundcolor=\color{pythonColor},%
+	stringstyle=\color{mylilas},%
+  	%identifierstyle=\bfseries\color{white},%
+  	basicstyle=\ttfamily\color{black},
+  	commentstyle=\color{pythonCommentColor},%
+    keywordstyle=\color{black},%
+    morekeywords=[2]{1}, keywordstyle=[2]{\color{black}},%
+    %identifierstyle=\color{black},%
+    stringstyle=\color{mylilas},%
+	frame=single,	                   % adds a frame around the code
+	breaklines=true,%
+    showstringspaces=false,%without this there will be a symbol in the places where there is a space
+    numbers=left,%
+    numberstyle={\tiny \color{black}},% size of the numbers
+    numbersep=9pt, % this defines how far the numbers are from the text
+    %emph=[1]{for,end,break},emphstyle=[1]\color{red}, %some words to emphasise
+    %emph=[2]{word1,word2}, emphstyle=[2]{style},  
+}
+
+
+
 
 \input{notations.tex}
 

misc/test/CMakeLists.txt

@@ -222,7 +222,8 @@ endif(BUILD_WRAPPER_MATLAB)
 #PYTHON WRAPPER
 if (BUILD_WRAPPER_PYTHON)
 	add_test(NAME PYTHON_FAUST COMMAND ${PYTHON_EXE} ${FAUST_SRC_TEST_SRC_DIR}/test_pyFaust.py ${FAUST_PYTHON_BIN_DIR})
-	add_test(NAME PYTHON_FAUST_INSTALL COMMAND ${PYTHON_EXE} ${FAUST_SRC_TEST_SRC_DIR}/test_pyFaust.py ${CMAKE_INSTALL_PYTHON_PREFIX})
+	add_test(NAME PYTHON_FAUST_DEMO_INSTALL COMMAND ${PYTHON_EXE} ${CMAKE_INSTALL_PYTHON_PREFIX}/quickstart.py ${CMAKE_INSTALL_PYTHON_PREFIX})
+	
 	
 	if(PYTHON_MODULE_SCIPY)
 		add_test(NAME PYTHON_FAUST_TIME COMMAND ${PYTHON_EXE} ${FAUST_SRC_TEST_SRC_DIR}/test_pyFaust_time.py ${FAUST_PYTHON_BIN_DIR} ${FAUST_BIN_TEST_FIG_DIR})

wrapper/python/CMakeLists.txt

@@ -28,8 +28,8 @@ if(BUILD_OPENBLAS)
 	set(FAUST_PYTHON_LIB ",'openblas'")
 endif(BUILD_OPENBLAS)
 
-
-
+#move quickstart demo file
+configure_file(${FAUST_PYTHON_SRC_DIR}/quickstart.py ${FAUST_PYTHON_BIN_DIR}/quickstart.py COPYONLY)
 
 # configure the setup.py.in into setup.py (equivalent of Makefile for Python)
 configure_file(${FAUST_PYTHON_SRC_DIR}/setup.py.in ${FAUST_PYTHON_BIN_DIR}/setup.py @ONLY)

wrapper/python/quickstart.py

+##############################################################################
+##                              Description:                                ##
+##    This demo shows that a Faust is handled as matlab builtin matrix,     ##
+## presenting  all the function that are overloaded for Faust class         ## 
+##                        (size,mtimes,transpose...)                        ##
+##                                                                          ##
+##  For more information on the FAuST Project, please visit the website     ##
+##  of the project : <http://faust.gforge.inria.fr>                         ##
+##                                                                          ##
+##                              License:                                    ##
+##  Copyright (2016):   Nicolas Bellot, Adrien Leman, Thomas Gautrais,      ##
+##                      Luc Le Magoarou, Remi Gribonval                     ##
+##                      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:                                    ##
+##      Nicolas Bellot  : nicolas.bellot@inria.fr                           ##
+##      Luc Le Magoarou : luc.le-magoarou@inria.fr                          ##
+##      Remi Gribonval  : remi.gribonval@inria.fr                           ##
+##############################################################################
+
+
+
+#import the FaustPy package
+import FaustPy;
+
+# import module to generate data
+import scipy
+from scipy import sparse as sp
+import numpy as np
+
+
+# generate the factors of the Faust
+dim1 = 1000;
+dim2 = 2000;
+nb_factor = 2;
+list_factor_sparse=[0]*nb_factor
+list_factor=[0]*nb_factor
+int_max = 120
+density_per_fact=0.1;
+list_factor_sparse[0]=int_max*sp.random(dim1,dim1,density=density_per_fact,format='csr',dtype=np.float64);
+list_factor[0]=list_factor_sparse[0].todense();
+list_factor_sparse[1]=int_max*sp.random(dim1,dim2,density=density_per_fact,format='csr',dtype=np.float64);
+list_factor[1]=list_factor_sparse[1].todense();
+
+
+
+
+# create a Faust named F from its factors
+A = FaustPy.Faust(list_factor)
+
+# get the size of the Faust
+print "dimension of the Faust : ", A.shape
+
+# transpose a Faust
+A_trans = A.transpose()
+
+# multiplication a Numpy matrix by a Faust
+x = np.random.randint(int_max, size=(dim2,1))
+y = A * x
+
+# convert a faust to numpy matrix
+A_numpy = A.todense()
+
+# slicing
+coeff = A[0,0]
+col_2nd = A[:,1]; 
+submatrix_A = A[3:5,2:3]
+
+
+
+# speed-up multiplication
+import time  
+nb_mult = 100
+t_dense = 0.0;
+t_faust = 0.0;
+
+for i in range(nb_mult):
+	x=np.random.randint(int_max, size=(dim2,1))
+	
+	t_begin = time.time()
+	y_dense = A_numpy.dot(x)
+	t_elapsed = time.time() - t_begin
+	t_dense += t_elapsed
+	
+	t_begin = time.time()
+	y_faust=A*x;
+	t_elapsed = time.time()-t_begin 
+	t_faust += t_elapsed
+
+print "multiplication SPEED-UP using Faust"
+print "Faust is "+str(t_dense/t_faust)+" faster than a full matrix"