 |
-
3.39.22
|
|
-
3.39.22
|
3. Testing and Troubleshooting
FAµST is designed for the Python ecosystem which as usual relies on the numpy and scipy packages.
If you want to run the FAµST demos (module pyfaust.demo), you'll also need the matplotlib package.
Please ensure these packages are installed on your system. One way to proceed is to use the pip program delivered with your python version.
pip install numpy scipy matplotlib # pygsp
# it could be pip3 instead of pip
Note that you probably have to install those packages for all versions of Python you want to use (each one has normally its associated pip executable).
Note also that you can rely on your system package manager to install the Python packages (e.g. dnf/yum repositories on Fedora/Centos Linux systems).
FAµST is compiled for Python 3.12.
If you want to use FAµST with Python 3 you must use precisely the 3.12 version because the FAµST Python wrapper delivered within the binary package is compiled for that minor version only.
The FAµST wrapper for Matlab has been tested on several Matlab versions starting from version 2016a,b up to version 2022b.
However it's not totally excluded that FAµST works with older and moreover newer versions.
You can just double-click the .pkg file to launch the installation process. You may need to authorize a non-appstore app installation into your preferences/security parameters or to right-click on the package from Finder then select 'Open' for a one-shot authorization that may require entering your password.
Alternatively, you can also proceed with the following command in a terminal:
$ sudo installer -pkg /path/to/faust-*.pkg -target /
WARNING: For the installation process to succeed you should respect the default destination path otherwise the auto-setup script for environment configuration won't work.
Likewise, if Matlab has not been installed in its default path, then it's most likely the auto-setup script won't find it, see below then for troubleshooting.
To avoid this issue you can symlink you matlab path into /Applications (the default path) as it follows:
$ sudo ln -sf /path/to/matlab/install/MATLAB/MATLAB_R2018b.app /Applications/MATLAB/ # you have to create the MATLAB folder if it doesn't exist yet
After installing the package:
Packages are available and tested for Debian, Ubuntu, Fedora and Centos.
For rpm based Linux distributions like Centos, Fedora, you must install FAµST with the following command :
$ sudo rpm -i faust-3.39.22-x86_64.rpm
# or equivalently if you're not in sudoers
$ su -c "rpm -i faust-3.39.22-x86_64.rpm"
For Debian and Ubuntu which use *.deb packages you must execute the next commands:
$ sudo dpkg -i faust-3.39.22-x86_64.deb
# or equivalently if you're not in sudoers
su -c "dpkg -i faust-3.39.22-x86_64.deb"
If the package installation fails claiming libmatio dependency isn't found, you should install it through your package manager, typically dnf on Fedora, yum on Centos and apt-get on Debian or Ubuntu.
On Fedora:
$ sudo "dnf -y install matio"
# or equivalently if you're not in sudoers
$ su -c "dnf -y install matio"
On Centos:
$ sudo "yum -y install matio"
# or equivalently if you're not in sudoers
$ su -c "yum -y install matio"
On Ubuntu or Debian:
$ sudo "apt-get install libmatio-dev"
# or equivalently if you're not in sudoers
$ su -c "apt-get install libmatio-dev"
Other alternative, especially for old versions of distributions, not updated anymore like Fedora 24, is to install the static version of FAµST package. It's needed because you could be stuck with a too much old version of matio. The adjective static means that matio library and its own dependencies are statically linked/integrated into the package binaries so you're free to install the package without installing matio. However it's not recommended to use this approach if you're system provides a sufficiently recent version of matio (>= 1.5.7, >= 1.5.23 is recommended).
The static packages for this release are:
faust-3.39.22-static-x86_64.rpm faust-3.39.22-static-x86_64.deb
After installing the package, you'll need to restart your Matlab or Python session in order to take into account the new configuration of your environment.
If Faust is not found, see below then for troubleshooting.
WARNING: Before starting, please close Matlab as it might prevent some files to be written during the installation process (especially if you are currently using FAuST).
WARNING: If you want to install pyfaust it's advisable to use the pip wheel package (.whl, look at this guide Installing pyfaust in Python virtual environments (Python venv & Anaconda)).
You can just double-click the .exe file to launch the installation process.
You may need to authorize the installation onto the windows panel opened just after clicking.
That may require you to run the installer as Administrator user, doing it by right clicking and choosing "Run As".
Alternatively, you can also proceed with the following command in a cmd.exe prompt:
C:\> runas /user:administrator \path\to\faust-*.exe
:: with administrator being the name of an account with Administrator rights
WARNING: For the installation process to succeed you should have Matlab and Python (relevant versions) set in your PATH environment variable (you can update it in Windows parameters). Of course if you want to use only the Python wrapper you don't need to worry about setting the PATH environment for Matlab and conversely. However the installer tries to install pyfaust and matfaust in all cases so if you have not installed python or matlab don't be afraid to see error messages (it is recommended to install Python in any case though). Note that if later you change your mind and want FAµST for the both languages you'll just need to relaunch the installer.
After installing the package, you'll need to restart your Matlab or Python session in order to take into account the new configuration of your environment.
Normally, after installing, nothing is left to do. The installation process should have seamlessly set up the Faust wrappers for Python and Matlab into your environment. Nevertheless, it could be useful to check that it really worked and set the environment manually if needed like explained below.
To test whether the FAµST Matlab wrapper auto-setup succeeded at install stage, you can open a terminal and type:
matlab -nodisplay -nojvm -r "matfaust.rand(10, 10, 'num_factors', 1, 'density', .5, 'fac_type', 'dense', 'field', 'complex')"
Note: if Matlab is not set in your PATH environment variable you need to replace ‘matlab’ with its full path (e.g. on macOS /Applications/Matlab/MATLAB_R2018b.app/bin/matlab)
It works only if you see an output similar to:
Faust size 10x10, density 0.50, nnz_sum 50, 1 factor(s):
- FACTOR 0 (complex) DENSE, size 10x10, density 0.5, nnz 50
% other values are possible for density, etc. because of the random generation
Otherwise it didn't work. So here is how to setup the wrapper manually.
First, launch a Matlab terminal, then go in the FAµST directory:
>> cd /opt/local/faust/matlab
Then launch the script that is responsible to add FAµST location in your Matlab path.
>> setup_FAUST
>> % then test again FAµST
>> matfaust.rand(10, 10, 'num_factors', 1, 'dim_sizes', 10, 'density', .5, 'fac_type', 'dense', 'field', 'complex')
Once matfaust path has been loaded into matlab environment you can save the configuration for future uses by simply typing:
>> savepath
The next time you'll run Matlab the matfaust package will be directly available.
Another way for that change of matlab path to be applied permanently, is to automatize the ‘addpath()’ call made by setup_FAUST.
For that purpose:
oldpwd=pwd;
cd /opt/local/faust/matlab; % for Windows users this is: C:\Program Files\faust\matlab
setup_FAUST
cd oldpwd;
Finally type ‘rehash toolbox’ in your current matlab terminal and restart Matlab in order to verify the configuration is permanent.
Note: you can also edit a user's specific startup.m script instead of system's startup.m. Look the Matlab documentation here.
OK! You can follow the quick start usage now.
To test whether the FaµST Python wrapper has been setup properly, simply open a terminal and type:
python3 -c "import pyfaust; print('It works.')"
# it could be python3.12 or just python,
# depending on your configuration and the python version you want to use
It goes without saying that if the wrapper is set up properly you'll see the message "It works." as a result of the command above.
On the contrary, the following error message
Traceback (most recent call last):
File "<string>", line 1, in <module>
ModuleNotFoundError: No module named 'pyfaust'
indicates that you need to add the Python wrapper manually in your Python path as demonstrated below.
$ export PYTHONPATH=$PYTHONPATH:/opt/local/faust/python3
# and test again
$ python3 -c "import pyfaust; print('It works.')"
set PYTHONPATH=%PYTHONPATH%;/opt/local/faust/python"
:: and test again
python3 -c "import pyfaust; print('It works.')"
If it fails again you are likely on a different version of Python or the auto-setup script failed for any reason during installation. Return to the Prerequisites section and check your Python environment matches FAµST requirements. Otherwise it works but you'll need to set the ‘export’ command manually in one of your startup scripts to have it set for once and for all (e.g. in ~/.bashrc if you are a Bash user).
On Windows you can set the PYTHONPATH environment variable in the configuration panel (system, advanced settings).
Finally, note that you may get another error message indicating for example that either numpy or scipy is not available.
ImportError: No module named numpy
For that issue look at Prerequisites.
OK! You can follow the quick start usage now.
Let's test FAµST with the quickstart script, from a matlab terminal type:
>> import matfaust.demo.quickstart.*
>> A = quick_start
And then call some functions on Faust object A to test a bit of the FAµST API:
>> rcg(A)
>> density(A)
>> numfactors(A)
>> help A.rcg
Retrieve the product factors:
>> F1 = factors(A,1);
>> F2 = factors(A,2);
Check the sizes:
>> size(F1)
>> size(F2)
>> size(A)
Check storage organization of the factors:
>> issparse(F1)
>> issparse(F2)
For more information on the FAµST API, and a whole function listing, consult the doc:
>> doc('matfaust.Faust')
>> % or:
>> import matfaust.*;doc('Faust')
N.B.: to access the documentation, you need to be in the graphical interface of Matlab.
Note that the doxygen documentation for the Matlab API is also available locally after installing Faust (in the installation folder). You can consult it online: namespacematfaust.html.
In the same spirit as the Matlab tutorial showed in the previous section, you can execute the quick start script for Python.
$ python3 -c "from pyfaust.demo import quickstart; quickstart.run()"
dimension of the Faust : (1000, 2000)
multiplication SPEED-UP using Faust
Faust is 1.83845941093 faster than a full matrix
Faust nnz: 300000
Faust density: 0.15
Faust RCG: 6.66666666667
Faust norm: 55156456.373
Faust nb of factors: 2
end quickstart.py
You can also go through the Python terminal to build a FAµST product and call its object methods.
$ python3
>>> import pyfaust
>>> A = pyfaust.Faust(filepath='A.mat') # A is the FAµST created through quickstart script
>>> A.rcg()
6.666666666666667
>>> A.density()
0.15
>>> A.numfactors()
2
>>> F1 = A.factors(0)
>>> F2 = A.factors(1)
>>> A.shape
(1000, 2000)
Note that the doxygen documentation for the Python API is also available locally after installing Faust (in the installation folder). You can consult it online: namespacepyfaust.html.
1.8.18