Repository files navigation

ATFA is theAmbiente de Testes para Filtros Adaptativos (Testingenvironment for adaptive filters).

This repository

• provides examples of adaptive filtering algorithms implemented in C++and C, and exposing the API that ATFA expects;
• explains how to understand the examples, how to modify them, how towrite your own algorithms, and how to compile them;
• provides scripts to compile the algorithms into the file format thatATFA expects, namely dynamic shared objects, or DSOs (*.so).

The algorithms must be compiled and linked into an*.so file. This canbe done manually, or by using the helper scriptbuild.py.Aditionally, the scriptbuild-all.sh can also be used to compileall of the examples at once.

If you just want to compile the examples to use from ATFA, type:

$cd atfa-examples$ bash build-all.sh

Seethe section on using thebuild.py script for more information.

ATFA accepts custom adaptive filtering algorithms in the form of dynamicshared object (*.so) files. Each adaptive filter DSO must export thefollowing symbols:

• adapf_init
• adapf_restart
• adapf_close
• adapf_run
• adapf_getw
• adapf_title
• adapf_listing

The last two (adapf_title andadapf_listing) are generatedautomatically by thebuild.py script. Below, each of thefunctions to be exported is explained:

Theadapf_init function initializes (e.g., acquires memory for) thedata structures that the algorithm will use. This data structure mightinclude, for example, the impulse response vector (vector of filtercoefficients), the input vector, and any other kind of parameter thatthe algorithm needs to keep track of.

This function must return a pointer to the initialized data.

This function resets the information contained indata (e.g., zeroesout the impulse response that has been learned so far), and returns apointer to the zeroed data. This function might free the memory pointedto by the old data and return a pointer newly allocated-and-initializedmemory.

This function releases the resources acquired inadapf_init. ATFA willcall it before closing the access to the DSO, in order to prevent memoryleaking. The pointer passed toadapf_close is the one returned byadapf_init, and the value returned fromadapf_close should be zeroif it fails and nonzero otherwise.

This is the function which implements the algorithm itself. Given anaudio sample from the input of the filter (sample) and an audiosample from the desired signal (y),adapf_run should calculatethe filter output, sayy_hat, and then return the errory - y_hat.

This function can read from and write to*data in order to accessand/or update values such as the filter coefficients, the inputvector (with memory), etc.

adapf_run is the only function that's called from within the audiorun-time loop. The other functions are all allowed to requestresources to the OS, and perform slow operations in general, but thisone isn't.

This function is called by ATFA in order to introspect the filtercoefficients. It must place at*begin a pointer to the first elementof the array of filter coefficients, and at*n the number of elementsthat can be read from that array (that is, the number of coefficients,which isN+1, whereN is the filter order).

This function should just return a static string containing a short"name" for the adaptive filter algorithm. For example, if the algorithmis an implementation of the NLMS algorithm withmu=0.7 andDelta=1.5, then the returned string could be"NLMS: 0.7, 1.5" ormaybe just"NLMS".

This function must return a static string, just likeadapf_title. Thestring returned fromadapf_listing is an algorithmic description ofthe adaptive filter, which is shown to the users when they click the"Show filter code" button in ATFA.

Inside theLMS/,NLMS/, andAP/ directories,you will find C++ source files implementing these three adaptivefiltering algorithms.

Theno-op/ direcory contains a file for a dummy algorithm,which does nothing at all. The source file insidestatic-w/ implements a static (instead of an adaptive)filter (the filter coefficients are never updated). Both of these canbe used for test purposes.

All of the above are implemented in C++. SeeLMS-C/ for anexample using plain C.

To compile an algorithm into a DSO file to be used with ATFA, you can doso manually—just generate an*.so that exports all of the functionsmentioned above—, or you can use thebuild.py helper script.

To use this script, open a shell inside the directory containing yoursource file(s), and then run the script. For example, to compile theLMS/ algorithm, type:

$cd atfa-examples$cd LMS$ python3 ../build.py

By default,build.py will compile and link all of the*.c and*.cpp files in the current directory. To use a custom set of sources,just pass them as arguments:

$ python3 ../build.py source1.cpp source2.cpp

The full set of source files specified on the command-line (or presentin the directory, if none is specified) must contain the definitions ofall of the functions mentionedabove, exceptatfa_title andatfa_listing. These will be automatically generated.

By default, the title is made up based on the command line, and thealgorithm listing is just a transcription of the source files. If youwant to use a custom title, use the-t/--title flag. If you want tospecify a custom file containing the listing, use the-l/--listingflag:

$ python3 ../build.py --title"My Algorithm" --listing my_algorithm.txt

If you want to provide theatfa_title oratfa_listing functionsyourself, use the+t or+l flags:

$ python3 ../build.py main_source.cpp title_and_listing.cpp +tl

For more options, type:

$ python3 ../build.py --help

You can also use the convenience scriptbuild-all.sh. This scriptwill just callpython3 ../build.py from inside each subdirectory of thecurrent directory. It will also pass the name of the directory in the--title flag.