Module
======

A :class:`Module <manta.module.Module>` defines a task within the Swarm and serves as the building block of any decentralized algorithm.
Each module represents an individual task that operates independently, performing computations based on the node's local data and contributing to the overall Swarm process.
Modules are executed within container environments, enabling isolated, reproducible, and scalable deployments across heterogeneous devices, from high-powered servers to edge devices.

Core Features of a Module
-------------------------

- **Containerized Execution**: Each module specifies a container image (e.g., Docker) that encapsulates the task environment, ensuring consistency across different nodes.
- **Task Independence**: Modules are self-contained, which means they can operate without dependencies on other modules except for defined communication or data exchange paths.

Creation of a Module
--------------------

To define a module, you create an instance of the :class:`Module <manta.module.Module>` class, specifying the script or the set of scripts that form the task, the container environment, and various execution parameters.
Below is an example of defining a Module:

.. code-block:: python

    from manta.module import Module
    from pathlib import Path

    # Define a Worker Module
    worker_module = Module(
        Path("modules/worker.py"),  # Path to the script defining the task
        "fl-pytorch-mnist:latest",  # Container image for task execution
        maximum=4,                  # Maximum number of instances allowed
        alias="worker",             # Alias for referencing the module in the Swarm
        method="any"                # Execution method (e.g., any, all)
    )

Modules constitue the backbone of the Swarm, allowing for the decomposition of complex algorithms into manageable, reusable, and scalable tasks that can be distributed across a network of devices.

.. note::

   The task (here :code:`modules/worker.py`) could be also a path of a folder which contains at least a :code:`__init__.py` file and a :code:`def main():` function within.

Key Parameters
**************

- **Path**: Specifies the location of the script(s) defining the task.
- **Container Image**: The Docker or similar image that encapsulates the task environment.
- **Maximum**: The maximum number of chosen nodes to run this module.
- **Alias**: A short name used to identify the module within the Swarm.
- **Method**: The execution method that defines how the module is scheduled (e.g., single execution or concurrent runs).

Connections between modules
---------------------------

Modules can be connected in order to form a graph.
For instance, you can connect two modules to a single one.

.. image:: ../_static/images/light-merge-modules.png
   :alt: Federated Learning Swarm
   :align: center
   :class: only-light

.. image:: ../_static/images/dark-merge-modules.png
   :alt: Federated Learning Swarm
   :align: center
   :class: only-dark

.. code:: python

   class FLSwarm(Swarm):

       def __init__(self):
           super().__init__()
           self.m1 = Module(...)
           self.m2 = Module(...)
           self.m3 = Module(...)

       def execute(self):
           m1 = self.m1()
           m2 = self.m2()
           m3 = self.m3([m1, m2])
           return m3

Also, you can do the opposite, which means connect one module to several ones.

.. image:: ../_static/images/light-split-modules.png
   :alt: Federated Learning Swarm
   :align: center
   :class: only-light

.. image:: ../_static/images/dark-split-modules.png
   :alt: Federated Learning Swarm
   :align: center
   :class: only-dark

.. code:: python

   class FLSwarm(Swarm):

       def __init__(self):
           super().__init__()
           self.m3 = Module(...)
           self.m4 = Module(...)
           self.m5 = Module(...)

       def execute(self):
           m3 = self.m3()
           m4 = self.m4(m3)
           m5 = self.m5(m3)
           return [m4, m5]

.. note::

   A Swarm can have multiple modules at the end of an iteration. You must return a list of modules for that.

.. note::

  For more detailed information on implementing a Module class, refer to the :class:`Module <manta.module.Module>` API Documentation.