8. Algorithms

Algorithms are user-defined piece of software that run within the blocks of a toolchain. An algorithm can read data on the input(s) of the block and write processed data on its output(s). For detailed information see the “Algorithms” section of “Getting Started with BEAT” in BEAT documentation.

8.1. Manipulating an Algorithm

The Algorithm editor can be accessed via the “User Resources” tab on your BEAT login page (click on “User Resources” and select “Algorithms” from the drop-down list). On your Algorithms page you should see something similar to the following:

../../../../../_images/SS_algorithms_info.png

Note the search-box and the privacy-filter above the list of algorithms displayed on the page. You can use these to limit your search. For example, entering “anjos” in the search-box will allow you to list only those algorithms that have the string “anjos” in the algorithm name. An example is shown in the image below.

../../../../../_images/SS_algorithms_anjos_search.png

There are several options when defining algorithms. They can be Analyzer, and Splittable. Analyzer algorithms are special algorithms where the purpose is to generate statistics about the processing results (graphs, means, variances, etc.). Usually, biometric data processing algorithms are Splittable, indicating to the platform that these algorithms can be executed in a distributed fashion, depending on the available computing resources.

There are also two types of algorithms depending on the way they handle data samples that are fed to them. They can be Sequential or Autonomous. For more information see the “Algorithms” section of “Getting Started with BEAT” in BEAT documentation.

There are two basic ways to create an algorithm at the BEAT platform. You may either start from scratch or fork a new copy of an existing algorithm and edit that.

8.1.1. Create an algorithm from scratch

To create an algorithm from scratch, start by clicking the ‘’new’’ button (green button on the top-right corner on the Algorithms page).

You should see a web-page similar to what is displayed below:

../../../../../_images/algorithm_new.png

For instructions on how to create an algorithm from scratch, please refer to the Section of algorithm editor and see the “Algorithms” section of “Getting Started with BEAT” in BEAT documentation to understand how to write the source code for new algorithms.

8.1.2. Edit an existing algorithm

In general, an existing algorithm that is already used in a toolchain cannot be edited. However, a new copy can be created by forking an existing algorithm, and this copy can be edited to create a new algorithm. The advantage is that the forked algorithm provides reference templates assisting user in creating the new algorithm. To fork an algorithm displayed in the list of algorithms, click on the violet ‘’fork’’ icon to the right of the algorithm name. You should see a webpage similar to what is displayed below

../../../../../_images/algorithm_fork.png

Please refer to the Section of Manipulating an Algorithm for creating an algorithm.

8.2. New Version

You can update your existing algorithm by clicking a new version button.

Please refer to the Section of Manipulating an Algorithm for creating an algorithm.

8.3. Editor

To create an algorithm, there are seven sections which are:

  • Name: the name of algorithm.

  • Algorithm option: Analyzer or Splittable.

  • Algorithm type: Sequential or Autonomous.

  • Language: The language used to implement the algorithm (Python or C++).

  • Endpoints: Define the properties of the Input and Output endpoints for this algorithm.

  • Parameters: Define the configuration-parameters for the algorithm.

When you have saved the algorithm you can add documentation that describes that algorithm as well.

For Python-based algorithms only:

  • Libraries: If there are functions in a library, you can add them for the algorithm to use.

  • Source code: The (Python) code implementing the algorithm.

You should see a webpage similar to what is displayed below:

../../../../../_images/algorithm_editor.png

8.3.1. How to debug?

Even though the BEAT platform is an evaluation system (as opposed to a development tool), porting algorithms to run on it may require some debugging, specially for blocks with multiple input groups with different synchronization channels. For that purpose, the standard output and error streams for each block ran in an experiment are logged for later inspection through the experiment view page (see our Experiments section). This include stack traces of uncaught exceptions, but also any data printed by an algorithm or associated libraries, on any of these streams.

You may take advantage of this to include print statements or similar in your algorithm code, to help with your debugging.

Warning

To comply with data privacy requirements in our terms of service, only the very last 4 kilobytes of these streams is kept for user inspection.

8.4. Implementing an algorithm in C++

8.4.1. Prerequisite: Configure your command-line client

In order to ensure that your compiled algorithm will works on the BEAT platform, you must compile it using our docker image docker.idiap.ch/beat/beat.env.client. Once downloaded, you’ll need to configure the command-line tool to access your account on the BEAT platform:

$ docker run -ti beatenv/beat.env.cxxdev:2.0.0r3 bash
/# cd home
/home# beat config set user <your_user_name>
/home# beat config set token "<your_token>"
/home# beat config save

Here, <your_user_name> is your username on the BEAT platform, and <your_token> can be retrieved from your settings page. Note that we use the /home folder to save everything, but feel free to use the one you want.

8.4.2. Algorithm compilation

To implement an algorithm in C++, follow the following steps:

1. Create the algorithm on the BEAT platform, by selecting the C++ language. Declare all the needed inputs, outputs and parameters.

2. Using the beat command-line tool, download the algorithm declaration from the BEAT platform (note that all the necessary data formats will be dowloaded too):

/home# beat algorithms pull <your_user_name>/<algorithm_name>/<version>

At this point, the folder /home/algorithms/<your_user_name>/<algorithm_name>/ will contain the declaration of your algorithm in JSON format, and /home/dataformats/ will contain the declaration files of the data formats used by the algorithm.

  1. Generate the C++ files corresponding to the algorithm declaration:

/home# generate_cxx.py . <your_user_name>/<algorithm_name>/<version>

At this point, the folder /home/algorithms/<your_user_name>/<algorithm_name>/ will contain a few new C++ files:

  • one header/source file for each needed data format

  • beat_setup.h and beat_setup.cpp: used by the platform to learn everything it needs to know about your algorithm

  • algorithm.h and algorithm.cpp: you will implement your algorithm in those files

Feel free to add as many other files as you need for your implementation.

  1. Implement your algorithm in algorithm.h and algorithm.cpp

5. Compile your code as a shared library (an example CMake file was generated, you can either modify it to add your own files or use another build system if you want). Note that the BEAT platform expect you to upload one and only one shared library, so if your algorithm has any dependencies, you must link them statically inside the shared library:

/home# cd algorithms/<your_user_name>/<algorithm_name>/
/home/algorithms/<your_user_name>/<algorithm_name># mkdir build
/home/algorithms/<your_user_name>/<algorithm_name># cd build
/home/algorithms/<your_user_name>/<algorithm_name>/build# cmake ..
/home/algorithms/<your_user_name>/<algorithm_name>/build# make

This will produce a file called <version>.so in the /home/algorithms/<your_user_name>/<algorithm_name>/ folder.

  1. Upload the shared library on the BEAT platform, from the algorithm page.

8.5. Sharing an Algorithm

As with other objects in the BEAT platform, algorithms may also be shared with other people or teams. For example, sharing algorithms may be useful in engaging a community in a challenge. In order to share your algorithm, while on the algorithm list display, click on the Share button. When you click this button, a window will appear allowing you to type in the usernames of users and teams you want to share your contribution with.

You may optionally choose to share the algorithm with all platform users and anonymous visitors by clicking on the checkbox Public. In this case, the fields for authorized users and teams are automatically disabled. Sharing is an irreversible procedure. You can only additively share contributions. You cannot unshare once the share is performed. You may cancel the operation by clicking on the Cancel button.

Note

Sharing status

The sharing status of an algorithm is represented to the left of its name, in the format of an icon. An algorithm can be in one of these four sharing states:

  • Private (icon shows a single person): If an algorithm is private, only you can use it on your experiments and only you can view its source code.

  • Usable (icon shows a cog): If an algorithm is usable, only you can view its source code. People on a sharing list can use the algorithm as a black-box (i.e. without looking at the source code) on their experiments. If there is no one on the sharing list, then everyone can use the algorithm.

  • Shared (icon shows many persons): If an algorithm is shared, only people on the sharing list can use the algorithm and view its source code.

  • Public (icon shows the globe): If an algorithm is public, then users and platform visitors can view the source code of the algorithm. All platform users can use the algorithm on their experiments.

Sharing at the BEAT platform is an irreversible procedure. For example, public objects cannot be made private again. If you share an object with a user or team and change your mind, you can still delete the object, for as long as it is not being used by you or another colleagues with access (see more information on our Frequently Asked Questions).

8.6. Deleting an Algorithm

An algorithm can only be deleted by deleting all the experiments that use it. Once deleted, the algorithm cannot be restored.