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. Implementing an algorithm in C++

8.1.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.1.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.

3. 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.

4. 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.

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

8.2. 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.3. Deleting an Algorithm

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