The SFT Algorithm

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 simple-to-use 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 wav-creation 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 output-function'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 fully-lengthed 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_tau-0.01_ma-50_mb-50_iters-1.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 direct-product 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 Matlab-function 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_tau-0.05_ma-30_mb-30_iters-1';
>> make_wav_from_sft(L,coeffs,G,name);

This creates a WAV file named "orchestra_short_tau-0.05_ma-30_mb-30_iters-1.wav" in the working directory.

Browse this site: Home | Java Usage | Matlab Usage
Created by Elizabeth Firman & Ariel Stolerman, CS Workshop, TAU Spring 2010