Mentions légales du service

Skip to content
Snippets Groups Projects
Commit 52b5b981 authored by Nicolas Bellot's avatar Nicolas Bellot Committed by hhakim
Browse files

experience QuickStart

parent 4afc0d5b
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
Showing
with 378 additions and 51 deletions
gen_doc/LaTeX/chapExample.tex
+ 9
− 2
View file @ 52b5b981
......@@ -5,9 +5,16 @@
\paragraph{} An experience of Brain Source Localization using several gain matrices including FAuSTs and several solvers is provided. You can execute the matlab script \textbf{demo/Brain\_source\_localization/BSL.m} to run this experiment and \textbf{demo/Brain\_source\_localization/Fig\_BSL.m} to display the following pictures illustrating the speed-up using a Faµst.
\paragraph{} An experience of Brain Source Localization using several gain matrices including FAuSTs and several solvers is provided. After configuring the matlab path (cf section \ref{sec:firstUseMatlabPath}). You can execute the matlab script \textbf{demo/Brain\_source\_localization/BSL.m} to run this experiment and \textbf{demo/Brain\_source\_localization/Fig\_BSL.m} to display the following pictures illustrating the speed-up using a Faµst.
You just need to type :
\begin{lstlisting}
>> BSL
>> Fig_BSL
\end{lstlisting}
Wich allows you to visualize this figure illustrating the speed-up with a Faust ($\mathbf{M}$ is the gain dense matrix and $\widehat{\mathbf{M}}_{6},\widehat{\mathbf{M}}_{9},\widehat{\mathbf{M}}_{16},\widehat{\mathbf{M}}_{26}$ are different Faust representing $\mathbf{M}$):
\begin{figure}[!htbp]
\label{fig:BSL}
\includegraphics[scale=0.8]{images/BSL.png}
\includegraphics[scale=0.7]{images/BSL.png}
\end{figure}
gen_doc/LaTeX/chapFirstUse.tex
+ 26
− 42
View file @ 52b5b981
......@@ -3,14 +3,18 @@
\paragraph{}A Matlab wrapper is delivered with the FA$\mu$ST C++ library.
It provides a user friendly new class of matrix \textbf{Faust} efficient for the multiplication with matlab built-in dense matrix class.\newline
\section{Configure Matlab path}\label{sec:firstUseMatlabPath}
In order to use matlab wrapper after the installation of Faust, launch Matlab.
In the Matlab terminal, set your working directory to /"HOMEDIR"/Documents/MATLAB/Faust and set the Matlab path by typing the following commands :
In the Matlab terminal, set your working directory to /"HOMEDIR"/Documents/MATLAB/Faust and configure the Matlab path by typing the following commands :
\begin{lstlisting}
>> cd /"HOMEDIR"/Documents/MATLAB/Faust
>> setup_Faust
\end{lstlisting}
\section{Use a faust from a saved one}\label{sec:firstUseBuildFromSave}
\paragraph{} Now, you can run quick\_start.m script in the Matlab terminal by typing :
\begin{lstlisting}
......@@ -18,60 +22,40 @@ In the Matlab terminal, set your working directory to /"HOMEDIR"/Documents/MATLA
\end{lstlisting}
\paragraph{}In this script, first of all, a Faust of size 4000x5000 is loaded from a previous one that is saved into a matfile :
\lstinputlisting[firstline=47,lastline=48]{../../misc/demo/Quick_start/quick_start.m}
\newpage
\paragraph{}Secondly, a list of overloaded matlab function shows that a Faust is handled as a normal Matlab builtin matrix.
\lstinputlisting[firstline=51,lastline=78]{../../misc/demo/Quick_start/quick_start.m}
\paragraph{}Finally, it performs a little time comparison between multiplication by a Faust or its full matrix equivalent.
This is in order to illustrate the speed-up induced by the Faust. This speed-up should be around 30 (depending on your machine).
\lstinputlisting[firstline=84,lastline=100]{../../misc/demo/Quick_start/quick_start.m}
A \textbf{Faust} object can be constructed from several ways.
%\lstinputlisting[firstline=84,lastline=100]{../../misc/demo/Quick_start/quick_start.m}
\section{Other ways to build a Faust}\label{sec:firstUseBuildFromCellArray}
\paragraph{} A Faust can initialized from a matrix or from a cell-array storing its factors.
\subsection{build a Faust from a matrix and parameters}\label{sec:firstUseBuildFromMatrix}
First, you can build a Faust from a cell-array of matlab matrix (sparse or dense) representing its factors.
\newline
\newline
The following example shows how to build a random faust of size 5x3 with 3 factors :
\begin{lstlisting}
>> nb_factor = 3;
>> dim1 = 5;
>> dim2 = 3;
>>
>> % list of factors
>> factors = cell(nb_factor);
>>
>> factors{1}=sprand(dim1,dim2,0.1); % first factor is rectangular and sparse
>> for i=2:nb_factor
>> factors{i}=rand(dim2,dim2); % second is sparse
>> end
>>
>> % build the faust
>> A=Faust(factors);
\end{lstlisting}
\newpage
An optional multiplying scalar argument can be taken into account :
\section{Construct a Faust from a given matrix}\label{sec:firstUseBuildFromMatrix}
\paragraph{} To see an example of building a Faust from a matrix, you can run factorise\_matrix.m in the Matlab terminal by typing :
\begin{lstlisting}
>> % multiplicative scalar
>> lambda = 3.5
>> % build the faust
>> A=Faust(factors,lambda);
>> factorise_matrix
\end{lstlisting}
In this script, from a given matrix A of size 100x200 :
\lstinputlisting[firstline=42,lastline=47]{../../misc/demo/Quick_start/factorise_matrix.m}
We generate the parameters of the factorisation from :\newline
-the dimension of A (\textbf{dim1} and \textbf{dim2}),\newline
-\textbf{nb\_factor} the number of factor of the Faust,\newline
- and \textbf{rcg} the Rational Complexity Gain, which represents the theoretical memory gain and multiplication speed-up of the Faust compared to the initial matrix
\lstinputlisting[firstline=51,lastline=56]{../../misc/demo/Quick_start/factorise_matrix.m}
Then we factorize the matrix \textbf{A} into a Faust \textbf{Faust\_A}
\lstinputlisting[firstline=58,lastline=59]{../../misc/demo/Quick_start/factorise_matrix.m}
And as for quickstart.m, we make some time comparison at the end.
This functionality allows you to build a Faust from the factorization algorithm :
\textbf{mexHierarchical{\_}fact} or \textbf{mexPalm4MSA} :
\newpage
\section{Construct a Faust from its factor}\label{sec:firstUseBuildFactors}
To see an example of building a Faust from its factors, you can run construct\_Faust\_from\_factors.m in the Matlab terminal by typing :
\begin{lstlisting}
>> % factorization step
>> [lambda,factors]=mexHierarchical_fact(params);
>> % build the faust corresponding to the factorization
>> A=Faust(factors,lambda);
>> construct_Faust_from_factors
\end{lstlisting}
This following example shows how to build a faust from a cell-array representing its factors.
\lstinputlisting[firstline=44,lastline=72]{../../misc/demo/Quick_start/construct_Faust_from_factors.m}
misc/demo/CMakeLists.txt
+ 5
− 3
View file @ 52b5b981
......@@ -42,9 +42,11 @@ if(BUILD_MATLAB_MEX_FILES)
endforeach()
##### Quick Start ##############################################
configure_file(${FAUST_DEMO_QUICKSTART_SRC_DIR}/quick_start.m ${FAUST_DEMO_QUICKSTART_BIN_DIR}/quick_start.m COPYONLY)
install(FILES ${FAUST_DEMO_QUICKSTART_BIN_DIR}/quick_start.m DESTINATION ${FAUST_DEMO_QUICKSTART_INSTALL_DIR} PERMISSIONS OWNER_READ OWNER_WRITE OWNER_EXECUTE GROUP_READ GROUP_WRITE GROUP_EXECUTE WORLD_READ WORLD_WRITE WORLD_EXECUTE)
file(GLOB TOOLS_MATLAB_SCRIPTS RELATIVE ${FAUST_DEMO_QUICKSTART_SRC_DIR} "${FAUST_DEMO_QUICKSTART_SRC_DIR}/*.m")
foreach(tools ${TOOLS_MATLAB_SCRIPTS})
configure_file(${FAUST_DEMO_QUICKSTART_SRC_DIR}/${tools} ${FAUST_DEMO_QUICKSTART_BIN_DIR}/${tools} COPYONLY)
install(FILES ${FAUST_DEMO_QUICKSTART_BIN_DIR}/${tools} DESTINATION ${FAUST_DEMO_QUICKSTART_INSTALL_DIR} PERMISSIONS OWNER_READ OWNER_WRITE OWNER_EXECUTE GROUP_READ GROUP_WRITE GROUP_EXECUTE WORLD_READ WORLD_WRITE WORLD_EXECUTE)
endforeach()
configure_file(${FAUST_DATA_MAT_DIR}/faust_quick_start.mat ${FAUST_DEMO_QUICKSTART_BIN_DIR}/faust_quick_start.mat COPYONLY)
install(FILES ${FAUST_DEMO_QUICKSTART_BIN_DIR}/faust_quick_start.mat DESTINATION ${FAUST_DEMO_QUICKSTART_INSTALL_DIR} PERMISSIONS OWNER_READ OWNER_WRITE OWNER_EXECUTE GROUP_READ GROUP_WRITE GROUP_EXECUTE WORLD_READ WORLD_WRITE WORLD_EXECUTE)
......
misc/demo/Hadamard_factorization/demo_fact_hadamard.m
+ 1
− 3
View file @ 52b5b981
......@@ -69,10 +69,8 @@ params.niter2 = 30;
params.update_way = 1;
params.verbose = 0;
[lambda, facts] = mexHierarchical_fact(matrix,params);
%% speed-up and relatice error
hadamard_faust = Faust(facts,lambda);
hadamard_faust = faust_decompose(matrix,params);
Xhat = full(hadamard_faust);
relative_error = norm(matrix - Xhat)/norm(matrix);
fprintf(['\n\n relative error between hadamard matrix and its transform : ' num2str(relative_error) '\n']);
......
misc/demo/Quick_start/construct_Faust_from_factors.m 0 → 100644
+ 72
− 0
View file @ 52b5b981
%% Description construct_Faust_from_factor
%
% This demo presents the method to build a Faust
% from its factors
% and ends with a little time comparison to illustrate
% the speed-up of using a Faust for multiplication.
%
% 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
% Adrien Leman : adrien.leman@inria.fr
% Thomas Gautrais : thomas.gautrais@inria.fr
% Luc Le Magoarou : luc.le-magoarou@inria.fr
% Remi Gribonval : remi.gribonval@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>
%
%%
% number of row of the Faust
dim1=300;
% number of column of the Faust
dim2=100;
% number of factor of the Faust
nb_factor=4;
% density of each factor
density_factor=0.1;
%cell-array representing its factors
factors = cell(1,nb_factor);
% 1st factor is a rectangular sparse matrix of density equal to density_factor
factors{1} = sprand(dim1,dim2,density_factor);
% all the others factor are square sparse matrix of density equal to density_factor
for i=2:nb_factor
factors{i} = sprand(dim2,dim2,density_factor);
end
%% construct the Faust
A_faust=Faust(factors);
% a multiplicative scalar can be taken into accoun to construct the Faust
lambda=2;
% B_faust=lambda*A_faust
B_faust=Faust(factors,lambda);
misc/demo/Quick_start/factorise_matrix.m 0 → 100644
+ 86
− 0
View file @ 52b5b981
%% Description factorise_matrix
%
% This demo presents the method to factorise a given matrix into a Faust
%
% 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
% Adrien Leman : adrien.leman@inria.fr
% Thomas Gautrais : thomas.gautrais@inria.fr
% Luc Le Magoarou : luc.le-magoarou@inria.fr
% Remi Gribonval : remi.gribonval@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>
%
%%
% number of row of the matrix
dim1 = 100;
% number of column of the matrix
dim2 = 200;
% matrix to factorise
A = rand(dim1,dim2);
% Rational complexity Gain (theoretical speed-up) of the Faust
rcg = 100;
% number of factor of the Faust
nb_factor = 2;
%% generate parameters of the factorisation
params = generate_params(dim1,dim2,nb_factor,rcg);
%% factorisation (create Faust from matrix A)
faust_A = faust_decompose(A,params);
%% speed-up multiplication
y=zeros(dim2,1);
nb_mult=100;
time_full=0;
time_faust=0;
x1=rand(dim2,1);
for i=1:nb_mult
tic
y=A*x1;
t1=toc;
tic
y=faust_A*x1;
t2=toc;
time_full=time_full+t1;
time_faust=time_faust+t2;
end
disp('multiplication SPEED-UP using Faust');
disp(['Faust is ' num2str(time_full/time_faust) ' faster than a full matrix']);
wrapper/matlab/CMakeLists.txt
+ 1
− 1
View file @ 52b5b981
......@@ -8,7 +8,7 @@
#file(MAKE_DIRECTORY ${FAUST_MATLAB_TOOLS_INSTALL_DIR})
# matlab tools directory
foreach(MATLAB_TOOLS FaustCore)
foreach(MATLAB_TOOLS FaustCore faust_decompose generate_params)
configure_file(${FAUST_MATLAB_TOOLS_SRC_DIR}/${MATLAB_TOOLS}.m ${FAUST_MATLAB_TOOLS_BIN_DIR}/${MATLAB_TOOLS}.m COPYONLY)
install(FILES ${FAUST_MATLAB_TOOLS_BIN_DIR}/${MATLAB_TOOLS}.m DESTINATION ${FAUST_MATLAB_TOOLS_INSTALL_DIR} PERMISSIONS OWNER_READ OWNER_WRITE OWNER_EXECUTE GROUP_READ GROUP_WRITE GROUP_EXECUTE WORLD_READ WORLD_WRITE WORLD_EXECUTE)
endforeach()
......
wrapper/matlab/tools/faust_decompose.m 0 → 100644
+ 52
− 0
View file @ 52b5b981
%% Description faust_decompose
%
%
% Faust_M = faust_decompose(M,params)
% decompose a matrix M into a Faust using parameters params
% the algorithm used is mexhierarchical_fact
%
% 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
% Adrien Leman : adrien.leman@inria.fr
% Thomas Gautrais : thomas.gautrais@inria.fr
% Luc Le Magoarou : luc.le-magoarou@inria.fr
% Remi Gribonval : remi.gribonval@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>
%
%%
function Faust_M = faust_decompose(M,params)
[lambda,fact]=mexHierarchical_fact(M,params);
Faust_M=Faust(fact,lambda);
end
wrapper/matlab/tools/generate_params.m 0 → 100644
+ 126
− 0
View file @ 52b5b981
%% Description generate_params
% Generates parameter of hierarchical_fact from a Matrix, the number of
% factor of the factorization and its RCG (Relative Complexity Gain)
%
% 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
% Adrien Leman : adrien.leman@inria.fr
% Thomas Gautrais : thomas.gautrais@inria.fr
% Luc Le Magoarou : luc.le-magoarou@inria.fr
% Remi Gribonval : remi.gribonval@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>
%%
function params = generate_params(dim1,dim2,nb_factor,RCG)
params.nrow=dim1;
params.ncol=dim2;
params.nfacts=nb_factor;
[min_dim,id_min_dim]=min([dim1 dim2]);
if (id_min_dim == 1)
params.fact_side=1; % left-side is factorized iteratively
dim1_residu=dim1;
dim2_residu=min_dim;
id_factor=nb_factor:-1:1;
line_residu=1;
line_fact=2;
else
params.fact_side=0; % right-side is factorized iteratively
dim1_residu=min_dim;
dim2_residu=dim2;
id_factor=1:nb_factor;
line_residu=2;
line_fact=1;
end
averaging_coeff=zeros(1,nb_factor);
dims_factor=zeros(2,nb_factor);% list of the dimension of the factors :
% -dim_factor(1,i) is the number of row of
% the ith factor
% -dim_factor(2,i) is the number of columns
% of the ith factor
dims_factor(:,1)=[dim1;min_dim];
for i=2:nb_factor-1
dims_factor(:,i)=[min_dim;min_dim];
end
dims_factor(:,nb_factor)=[min_dim;dim2];
nb_coeff_per_fact=prod(dims_factor);
total_nb_coeff=sum(nb_coeff_per_fact);
density_fact=(dim1*dim2)/(total_nb_coeff*RCG);% if Matrix is squared, alpha = 1/(nb_factor*RCG)
% each factor has the same density equal to 1/(RCG*nb_factor)
factor_constraint=cell(1,nb_factor);
% each factor has the same density
for i=id_factor
% constraint,nb_nnz,nb_row,nb_col of the factor
dim1_factor=dims_factor(1,i);
dim2_factor=dims_factor(2,i);
factor_constraint{i}={'sp',density_fact*nb_coeff_per_fact(i),dim1_factor,dim2_factor};
end
decrease_speed=exp(log(density_fact)/(nb_factor-1));
params.cons=cell(2,nb_factor-1);
params.cons(line_fact,1:nb_factor-1)=factor_constraint(id_factor(1:end-1));
%params.cons(line_fact,nb_factor-1)=factor_constraint(id_factor(end)); %last residuum is a factor
for i=1:nb_factor-1
params.cons{line_residu,i}={'sp',decrease_speed^i*dim1_residu*dim2_residu,dim1_residu,dim2_residu};
end
end
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment