.. vim: set fileencoding=utf-8 :

.. Copyright (c) 2016 Idiap Research Institute, http://www.idiap.ch/          ..
.. Contact: beat.support@idiap.ch                                             ..
..                                                                            ..
.. This file is part of the beat.docs module of the BEAT platform.            ..
..                                                                            ..
.. Commercial License Usage                                                   ..
.. Licensees holding valid commercial BEAT licenses may use this file in      ..
.. accordance with the terms contained in a written agreement between you     ..
.. and Idiap. For further information contact tto@idiap.ch                    ..
..                                                                            ..
.. Alternatively, this file may be used under the terms of the GNU Affero     ..
.. Public License version 3 as published by the Free Software and appearing   ..
.. in the file LICENSE.AGPL included in the packaging of this file.           ..
.. The BEAT platform is distributed in the hope that it will be useful, but   ..
.. WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY ..
.. or FITNESS FOR A PARTICULAR PURPOSE.                                       ..
..                                                                            ..
.. You should have received a copy of the GNU Affero Public License along     ..
.. with the BEAT platform. If not, see http://www.gnu.org/licenses/.          ..


.. _beat-system-libraries:

===========
 Libraries
===========

Algorithms are fundamental elements in the BEAT framework that formally describe how
to process data. In particular, they are always attached to a specific
processing block with a given set of inputs and outputs. When an algorithm
needs to be applied in a slightly different processing block, this may, hence,
lead to a lot of code duplication. Duplicate code is undesirable for a number
of reasons such as high maintenance cost.

To address this problem, the concept of **libraries** has been defined.
Libraries allow users to put code required by several different algorithms
into a common location. Once done, code from a library may be used by any
algorithm as long as the algorithm mentions its dependency to it in its
JSON declaration. In addition, a library may depend on another library.

.. note:: **Naming Convention**

   Libraries are named using three values joined by a ``/`` (slash) operator:

     * **username**: indicates the author of the library
     * **name**: indicates the name of the library
     * **version**: indicates the version (integer starting from ``1``) of the
       library

   Each tuple of these three components defines a *unique* name inside the
   framework.


Definition
----------

Similarly to algorithms, a library consists of two folds:

* A ``JSON declaration`` indicating:

  - The language in which the library is written
  - Library dependencies of this library

.. code-block:: javascript

    {
        "uses": {
            "otherlib": "user/otherlibrary/1"
        },
        "language": "python"
    }


* ``Source code``. For the Python back-end, this may consist of any Python
  function and classes, as long as dependencies are fulfilled.

.. code-block:: python

    def simple_function(array):
        return len([v for v in array if v != 0])

    class MyLibraryClass:

        def __init__(self, multiplier=37):
            self.multiplier = multiplier

        def function_from_my_library(value):
            return value * self.multiplier

..note ::

   The graphical interface of BEAT provides user-friendly editors to configure
   the main components of the system (for example: libraries, data formats,
   etc.), which simplifies their `JSON`_ declaration definition. One needs
   only to declare a library using the described specifications when not using
   this graphical interface.



Usage
-----

To use a defined library in an algorithm or in another library, it is
sufficient to:

* Add the library dependency into the `JSON`_ declaration of the algorithm
  (or of the library). The name given as a key is the one used to import
  the library, while the corresponding value is the full name, that is
  `author/name/version` of the library.

.. code-block:: javascript

    {
        ...
        "uses": {
            "mylib": "user/mylibrary/1"
        },
        ...
    }

* Import the library and use its desired functionalities.

.. code-block:: python

    import mylib
    ...
    array = [0, 1, 2, 3]
    array_processed = mylib.simple_function(array)


.. include:: links.rst