
Raisin: To perform cluster work easily!
=======================================

Project Philosophy
^^^^^^^^^^^^^^^^^^
| The main aim of *raisin* project is to **share physical resources** of your laptop with a community.
| In counterpart, you can **benefit from the community resources**.
| There are 2 sides in this project:

1.Resources usage
^^^^^^^^^^^^^^^^^
| The *raisin* API wants to be as close as possible to the 'threading' and 'multiprocessing' python APIs.
| The advantage in using *raisin* rather than 'threading' or 'multiprocessing' is that the computing power is greatly increased (depending on the number of connected resources).
| Though *raisin* is based on 'multiprocessing' module - that splits tasks among the resources of a single computer - it also shares the load over the different machines in the network. Everything is automatically and intelligently orchestrated relying on code analysis and graph theory.

*raisin* wants to be **as simple as possible**. That’s why the code analysis and the resources management are automated. Also *raisin* uses a bunch of classes and functions default parameters that are suitable for most usages.

| However, you can tune *raisin* behavior as you want since all these parameters are **fully customizable**.
| *raisin* is a multi-OS module 100% written in python in order to keep installation reliable and simple.
| Although *raisin* uses powerful modules such as 'sympy', 'numpy', 'giacpy', 'pycryptodomex', 'tkinter'... these modules are not required (they are sometimes not easy to install). This will just lead to less efficiency, but no failure!

In a future version, *raisin* will be able to perform automatic parallelization, a little like 'pydron'.

2.Resources sharing
^^^^^^^^^^^^^^^^^^^

| To be able to use community resources, you must give in return!
| That’s why, when *raisin* is installed as a python package, you have to install the 'application' part.
| To do this, execute the ``python -m raisin install`` command.

| The **security** is a primordial aspect.
| You can join or create your own cluster (e.g. friends working on a same project, ...), one at a time. The different clusters are waterproof between them. The data are encrypted. Machines must identify one another within a given cluster.

Your comfort while you are offering resources is guaranteed. *raisin* is **not intrusive**, it uses your resources - RAM, CPU, fan noise and bandwidth - only if they are available. Naturally, you keep hands on the way you are sharing your resources (timetable, rate, ...).

Resource sharing, including security, is graphically **configurable**. Simply run ``python -m raisin configure`` command.

Installation
------------
From PyPI using pip:

.. code-block:: bash

        sudo pip install --upgrade raisin
        python -m raisin install

Development version from 'framagit':

.. code-block:: bash       

        git clone https://framagit.org/robinechuca/raisin
        cd raisin
        pip install -r requirements.txt
        sudo python setup.py install
        python -m raisin install
        cd ..
        rm -rf raisin

Basic examples
--------------

.. code:: python

    In [1]: import raisin
       ...:
       ...: def foo(x):
       ...:   """Function long at execution."""
       ...:   ...
       ...:   return x**2

    In [2]: p = raisin.Process(foo, args=(5,)) # More options.
       ...: p.start() # Hand back, parallel execution.
       ...: p.get() # Wait and return result.
    Out[2]: 25

    In [3]: list(raisin.map(foo, range(5))) # More options.
    Out[3]: [0, 1, 4, 9, 16]


* `See the integrated documentation for more details and examples <https://framagit.org/robinechuca/raisin/-/blob/master/raisin/__init__.py>`_.
 
Main Functions
--------------

* Cluster work, with automatic distribution, recording results and protocol resumption.

+----------------+---------------------------------------------------+
| Package        | Basic Description                                 |
+================+===================================================+
| raisin.Map     | runs a function n times, one per each argument    |
+----------------+---------------------------------------------------+
| raisin.map     | same as python built-in 'map', but over a cluster |
+----------------+---------------------------------------------------+
| raisin.Process | executes the function in the background           |
|                | (similar to & unix command)                       |
+----------------+---------------------------------------------------+
| raisin.process | same as Process, but blocking                     |
+----------------+---------------------------------------------------+
| raisin.Scan    | executes a function by scanning arguments         |
+----------------+---------------------------------------------------+
| raisin.scan    | like 'Scan' but blocking                          |
+----------------+---------------------------------------------------+

* Serialization / Deserialization, with intercompatibility, encryption, compression and RAM saving.

+--------------------+-------------------------------+
| Package            | Basic Description             |
+====================+===============================+
| raisin.dumps       | serialisation (to str)        |
+--------------------+-------------------------------+
| raisin.loads       | deserialisation (from str)    |
+--------------------+-------------------------------+
| raisin.dump        | serialisation (to file)       |
+--------------------+-------------------------------+
| raisin.load        | deserialisation (from file)   |
+--------------------+-------------------------------+
| raisin.serialize   | serialisation (to bytes)      |
+--------------------+-------------------------------+
| raisin.deserialize | deserialisation (from bytes)  |
+--------------------+-------------------------------+
| raisin.copy        | real copy using serialization |
+--------------------+-------------------------------+

* More tools.

+--------------------------------+------------------------------------------+
| Package                        | Basic Description                        |
+================================+==========================================+
| raisin.tools.MergeGenerators   | asynchronous merge iterator              |
+--------------------------------+------------------------------------------+
| raisin.tools.id                | retrieves lots of contextual information |
+--------------------------------+------------------------------------------+
| raisin.tools.Lock              | locks with possibility of mondial reach  |
+--------------------------------+------------------------------------------+
| raisin.tools.Printer           | friendly display                         |
+--------------------------------+------------------------------------------+
| raisin.tools.timeout_decorator | adds a timeout on any function           |
+--------------------------------+------------------------------------------+
| raisin.tools.get_temperature   | gets CPU temperature                     |
+--------------------------------+------------------------------------------+
