Browse this site: Home  Java Usage  Matlab Usage
Learning and Coding Theory Workshop
The SFT Matlab Usage
Summary
This project includes an integration with Matlab, allowing Matlab users to use the Java SFT calculation embedded in
simpletouse Matlab scripts. The difference between the Java usage and the Matlab usage, other than the environment,
is that the Matlab SFT scripts use matlab objects  vectors and functions  and return a Matlab object as well, so
the usage can be integrated in a normal Matlab code flow.
Usage
In order to use the SFT Matlab package, follow these steps:

Download: download the environment files and scripts.

Matlab environment setup: set the environment in order to be able to use the scripts, as described below.

Use: write your Matlab code and use the SFT methods just as any other Matlab script.
Package Contents:
To better understand the package scripts and description, first read the Java usage page and the SFT javadoc.
The main scripts include a detailed documentation (inputs and output description).

sft_setenv.m: this script has to be ran every time you open Matlab and want to use the SFT package.
It simply adds the JAR file to Matlab's Java path.
After you download and place the JAR file where you want, you must change the JAR path in this script
in order for it to work.

sft_dp.m: for running the SFT on a function over a Cartesian product of finite groups with
given m_{A} and m_{B}.

sft_dp_full.m: for running the SFT on a function over a Cartesian product of finite groups with
all the parameters for calculating m_{A} and m_{B} as described in the paper.

sft_fa.m: for running the SFT on a function over a finite Abelian group with
given m_{A} and m_{B}.

sft_fa_full.m: for running the SFT on a function over a finite Abelian group with
all the parameters for calculating m_{A} and m_{B} as described in the paper.

dp_func_res_from_fa_func.m: given a finite Abelian domain representation G, a function over this domain
and an element x in the corresponding direct product domain, returns the function's value over the corresponding
finite Abelian element. Used in the sft_fa.m and sft_fa_full.m scripts.

func_from_sft.m: for usage in the wavcreation scripts. Given L,coeffs  the output of the SFT, G  a WAV
function domain (i.e. positive N representing Z_{N}) and x, it calculates the outputfunction's value in x.

wav_func_script.m: if you want to give a WAV file as an input function for the SFT methods you need to:

Read the WAV file into a variable m: m = wavread('filepath');

Define a function that uses this script: func = @(x,G)wav_func_script(x,m);
Note that G here has no meaning, but func must be defined as above to be a valid input for the SFT scripts. The real
G value is given separately when invoking the sft script, in this case where G = Z_{N}: G = size(m,1);
func can be used as an input function.

make_wav_from_sft.m: given L,coeffs  the output of the SFT, G  a WAV function domain (i.e. positive N representing Z_{N})
and a name (string), this script creates a WAV file with the given name, generated from the given SFT output. Since the SFT ouput is
only an approximated function, some values may be over 1 or below 1, and so a normalization of the output is applied. This causes
the resulted WAV to be amplified by some 0 < a < 1.

make_wav_from_sft_departed.m: given the sft_dp.m parameters, m  a wavread output, sizeOfInterval 
the size of the intervals to divide the function's domain into, and name  a name for the output WAV, this script
divides the given WAVREAD output (in m) into size(m)/sizeOfInterval intervals. It then runs the SFT on parts of m,
and eventually it creates from all the SFT outputs approximated WAV parts and concatenates them into one fullylengthed WAV file.
Since the SFT ouput is only an approximated function, some values may be over 1 or below 1, and so a normalization of the output is applied.
This causes the resulted WAV to be amplified by some 0 < a < 1.
Examples:
DOWNLOAD EXAMPLES
The examples zip file above includes 3 WAV samples and some WAV outputs created using the SFT scripts with varying parameters. It also includes
an example for a matlab written function and a runner script  the example given below in details. Note that all parameters given to the SFT for
generating a WAV output for the 3 WAV files, are detailed in the output file name (e.g.
orchestra_tau0.01_ma50_mb50_iters1.wav).
Testing details on the WAV files:

guitar.wav (8.73 secs, G = Z_{384,860}): tested dividing the original file into intervals of length 30,000,
running the SFT on each interval separately and combining the results together to create a continuing output in the original length.
Also tested with the same parameters only without division to subintervals.
This method gives better percision for each interval, but when concatenting the outputs together the points of connection are noticable.
Comparing the undivided with the divided, it can be heard that the notes are sharper in the divided and more dimmed in the undivided.

orchestra.wav (5.33 secs, G = Z_{235,200}): tested several times using sft_dp.m with varying τ, m_{A} and
m_{B} (but with number of iterations being 1 in all examples).
The results show that as the threshold τ decreases, the output sounds more like the original but also the noise increases and covers
it more and more. Also, as the size of m_{A} and m_{B} increases, the percision increases.
Note: it is best to listen to the output samples using headphones in order to hear the main tone clearly through the noise (it is
weakened due to the normalization done when creating the WAV file).

orchestra_short.wav (0.68 secs, G = Z_{30,000}): since this sample is short it was easier to test and create output WAV files
from the approximated functions generated from the SFT outputs. This sample contains outputs generated using varying threshold (τ),
m_{A} and m_{B} and number of iterations. There is also an output generated using sft_dp_full.m.
This code example (included in the examples zip file) demonstrates how to use the Matlab SFT package including the environment setup.
The following will describe the example for a function over a directproduct of finite groups domain:
Step #1: extract the zip file into your home directory and edit sft_setenv.m. Here the files are
extracted into a directory named sft.
Step #2: the sft_setenv.m file contains one line for importing the SFT JAR file:
% environment setup for SFT usage
javaaddpath('/specific/a/home/cc/students/cs/arielst1/sft/sft_lib.jar')
Change the path between the two " ' " to the sft_lib.jar file path you chose.
Step #3: run Matlab, set the environment and start working.
The example below shows a simple usage in Matlab prompt, that uses an example Matlabfunction script.
>> sft_setenv % setting up the environment
>> % set parameters
>> isLogged = true;
>> G = 10^10;
>> tau = 200;
>> func = @(x,G)test(x,G);
>> numOfIterations = 1;
>> delta_t = 0.01;
>> fInfNorm = 28.41;
>> fEucNorm = 20;
>> deltaCoeff = 1;
>> maCoeff = 0.0001;
>> mbCoeff = 0.0001;
>> etaCoeff = 1;
>> % RUN THE SFT ALGORITHM
>> [L,coeffs] = sft_dp_full(isLogged,G,tau,func,numOfIterations,delta_t,
fInfNorm,fEucnNorm,deltaCoeff,maCoeff,mbCoeff,etaCoeff);
... printing out SFT run log
>> L
L =
230
1492
>> coeffs
coeffs =
7.45894795692530 +10.71743484383209i
10.74807983709623 + 7.47732998509190i
Another code example for creating an SFT output WAV file:
>> % set variables and run SFT
>> m = wavread('orchestra_short.wav');
>> isLogged = true;
>> G = size(m,1);
>> tau = 0.05;
>> func = @(x,G)wav_func_script(x,m);
>> ma = 30;
>> mb = 30;
>> numOfIterations = 1;
>> [L,coeffs] = sft_dp(isLogged,G,tau,func,ma,mb,numOfIterations)
... printing out SFT run log
>> % create WAV file from the output
>> name = 'orchestra_short_tau0.05_ma30_mb30_iters1';
>> make_wav_from_sft(L,coeffs,G,name);
This creates a WAV file named "orchestra_short_tau0.05_ma30_mb30_iters1.wav" in the working directory.
Browse this site: Home  Java Usage  Matlab Usage
Created by Elizabeth Firman & Ariel Stolerman, CS Workshop, TAU Spring 2010