lib@home, framework to develop distributed calculations. Copyright (C) 2020 Dirk "YouDirk" Lehmann

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program 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. See the GNU Lesser General Public License for more details.

You have received a copy of the GNU Lesser General Public License along with this program. If not, see https://www.gnu.org/licenses/.

Readme (lib@home)

A framework to develop *@home projects for distributed calculations.

Currently this project is in an very early state and the lib@home library is not really usable for productive stuff. But if you are interested in it, we provide the following resources to check the current progress of development

• lib@home API Reference Documentation
  https://youdirk.github.io/libathome-doc/

• lib@home Project on GitHub
  https://github.com/YouDirk/libathome

• lib@home Bug Tracking
  https://github.com/YouDirk/libathome/issues

• lib@home Donate/Sponsor
  https://github.com/sponsors/YouDirk

What is lib@home?

The goal is to develop a software library that can be used for large (time intensive) calculations which are possible to split into separate tasks. There will be exist a server-side implementation for Linux, which is possible to configure as reverse proxy for common HTTP server applications (such like Apache) for easy integration into existing WWW server (hopefully without re-configuring firewall stuff) and the possibility to separate the lib@home-server process to a remote cloud-machine. The lib@home-server process with a SQL database (MariaDB and PostgreSQL planned) distributes the tasks to the lib@home-user-clients (Windows and Linux implementation) which solves the task if it is currently not busy with optionally graphical output, such like a much calculation intensive screensaver. If the task is solved the task-result will be sent to the server which verifies the task-result, and if it is a really possible solution then it can be saved to the database and used for later tasks. So far, one task can be interpreted as one iteration of the large calculation.

Additionally there is an achievement system planned. Every client is logged-in via a cryptographic challenge-response authentication using OpenSSL, this mechanism makes it easy to register a new user-client without an user-interaction. So every user have a public (by default anonymous) user profile, where are statistics available and achieved successes are logged for other community members. It's also planned to provide some global statistics, such like the progress of the large calculation problem and optionally to provide some results of it.

Common use-cases may be to train AI algorithms. As you can imagine, the concept of this library does only work if the calculation itself is useful for the general public, and that is the goal of lib@home. So, nowadays the scientists in biology and public healthy are interested in which DNA/RNA sequences matching which property of an organism/virus. Categorizing properties depending on DNA/RNA sequences is a very popular topic which could be solved with very long calculating training algorithms of Artificial Neural Networks, Support Vector Machines, etc. Mining digital currencies, such like Bitcoin, is not a goal of this library.

You can find an example application, called Prime@home in the lib@home repository on GitHub. The task which will be distributed to the client here is just an incrementing integer (for example 45). The client takes this number and calculates the prime-factors of it (in this example 3 * 3 * 5 = 45) and send these back as task-result (here {3, 3, 5}). The server verifies the task-result by multiplying these factors (3 * 3 * 5 is really 45). If the verification succeeded, then the server writes the relation to the SQL database (id=45 -> {(45, 2, 3), (45, 1, 5)}). Now the database can be queried to get fast the prime-factors.

Make targets

all <default>: Compiles the current directory and all sub-directories
recompile:     Runs 'clean' followed by 'all'
clean:         Deletes temporary files / prepare for recompilation
               Useful on 'Header file not found' compilation errors
clean-all:     Deletes all files which are not under version control
clean-doc:     Deletes all files generated by 'doc'
debug:         Compiles 'all' and runs 'project' in debugger (GDB)
debug-emacs:   Run 'project' in debugger (GDB) with Emacs support
doc:           Create a Doxygen documentation of the current directory
doc-view:      Runs 'doc' and show the resulting documentation in Browser
run:           Make 'all' followed by running 'project'
run-leakcheck: Same as 'run', but execute 'project' in Valgrind
tags-all:      Make 'tags-ctags', 'tags-etags' and 'tags-ebrowse'
tags-ctags:    Runs 'ctags' indexer for TAB auto-completion
tags-ebrowse:  Runs 'ebrowse' indexer for TAB auto-completion in Emacs
tags-etags:    Runs 'etags' indexer for TAB auto-completion

Playing around with lib@home

Debian (Linux)

The main development is done on Linux. If you are using Debian (or Ubuntu) you need to have installed at least make, g++ and libc-dev, these packages are part of Debian package build-essential. Also you need to install git. If you are finished and have cloned the repository to your local machine then run make to check for other dependencies.

$> sudo apt-get install git build-essential
$> git clone https://github.com/YouDirk/libathome libathome
$> cd libathome
libathome$> make run

Hint: To automatically check the make-targets which are available on-the-fly using TAB auto-completion, it is recommended to install the Debian package $> apt-get install bash-completion. After doing this, open a new Bash shell, type libathome$> make and use the TAB-key twice to list the make-targets.

MSYS2/MinGW (Windows)

If you are using Windows you need to install MSYS2 (https://www.msys2.org). After installation is finished, run a MSYS2-shell and make the system up-to-date by running

$> pacman -Syu

Then install at least the following MSYS2/MinGW packages: git, make and g++. If you are finished and have cloned the repository to your local machine then run make to check for other dependencies.

$> pacman -S msys/git msys/make mingw64/mingw-w64-x86_64-gcc
$> git clone https://github.com/YouDirk/libathome libathome
$> cd libathome
libathome$> make run

Hint: To automatically check the make-targets which are available on-the-fly using TAB auto-completion, it is recommended to install the MSYS2 package $> pacman -S msys/bash-completion. After doing this, open a new Bash shell, type libathome$> make and use the TAB-key twice to list the make-targets.

Credits

• Donators:
  nobody1, nobody2, nobody3 D':

• Regular contributors:
  Dirk "YouDirk" Lehmann