Metadata-Version: 2.4
Name: hydrofed
Version: 0.1.0
Summary: A Reusable, Model-Agnostic Decentralized Federated Learning Framework based on Hydraulic Water-Flow Consensus
Author: M Sathya (Research Guide)
Author-email: Soundarya R <soundaryaramachandra2003@gmail.com>, Tanmaie P U <tanmaiepu@gmail.com>, Trishika S <trishikas295@gmail.com>, Shambhavi E L <shambhaviprofile@gmail.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/Soundarya-2004/Hydrofed-ICAF-Pypi
Project-URL: Repository, https://github.com/Soundarya-2004/Hydrofed-ICAF-Pypi
Project-URL: Documentation, https://github.com/Soundarya-2004/Hydrofed-ICAF-Pypi#readme
Project-URL: Bug Tracker, https://github.com/Soundarya-2004/Hydrofed-ICAF-Pypi/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=1.12.0
Requires-Dist: numpy>=1.20.0
Requires-Dist: cryptography>=3.4.0
Provides-Extra: examples
Requires-Dist: torchvision>=0.13.0; extra == "examples"
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Requires-Dist: pytest-cov>=4.0.0; extra == "test"
Provides-Extra: all
Requires-Dist: torchvision>=0.13.0; extra == "all"
Requires-Dist: pytest>=7.0.0; extra == "all"
Requires-Dist: pytest-cov>=4.0.0; extra == "all"
Dynamic: license-file

# HydroFed: Decentralized Hydraulic Federated Learning Framework

[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/Python-3.9%20%7C%203.10%20%7C%203.11-brightgreen.svg)](pyproject.toml)
[![Architecture](https://img.shields.io/badge/Architecture-Decentralized%20Peer--to--Peer-orange.svg)](docs/architecture.md)

**HydroFed** is a reusable, model-agnostic, and modality-agnostic decentralized federated learning framework. Drawing inspiration from **hydraulic water-flow dynamics**, HydroFed coordinates peer-to-peer model synchronization through pressure-driven parameter exchanges with strict mathematical parameter conservation, asynchronous staleness damping, and pluggable authenticated encryption.

---

## Key Features

- **Decentralized Hydraulic Consensus**: Replaces centralized server bottlenecks with pairwise parameter transfers driven by model disagreement pressure.
- **Exact Parameter Conservation**: Preserves total weight mass across communication edges: $\Delta W = \eta_{ij} \cdot (W_j - W_i)$.
- **Asynchronous Staleness Damping**: Attenuates delayed updates via rational decay: $\eta_{\text{scaled}} = \frac{\eta}{1 + \beta \cdot \text{staleness}}$.
- **Structured Topologies**: Native support for `ring`, `grid`, `random_graph`, and `small_world` topologies with guaranteed connectivity verification.
- **Model-Agnostic & Modality-Agnostic**: Compatible with CNNs, MLPs, Transformers, LSTMs, tabular models, and vision models.
- **Strict Schema Compatibility**: Enforces architecture ID, version, parameter name, shape, and dtype matching to reject incompatible updates.
- **Defense-in-Depth Security**: Pluggable AES-256-GCM authenticated encryption, 12-byte random nonces, and heuristic parameter anomaly detection.
- **Decoupled Data Partitioning**: Configurable uniform IID and Dirichlet Non-IID distributions ($\alpha$ configurable, e.g. 0.1, 0.3, 0.5, 1.0).
- **Configurable Client Scaling**: Supports **1 to 60 simulated clients** (`MAX_CLIENTS = 60`).

---

## The Water-Flow Conceptual Analogy

HydroFed translates physical fluid principles into decentralized machine learning operations:

| Fluid Analogy | HydroFed Machine Learning Component |
| :--- | :--- |
| **Water Level** | Local model parameter state $W_i$ |
| **Pressure Difference ($\Delta P$)** | Parameter disagreement norm $\|W_j - W_i\|_2$ |
| **Pipe Hydraulic Resistance ($R_{ij}$)** | Communication channel resistance / cost |
| **Flow Coefficient ($\eta_{ij}$)** | Adaptive exchange learning rate |
| **Water Movement** | Parameter delta transfer $\Delta W$ |
| **Conservation of Mass** | Symmetric parameter conservation ($\Delta W_i + \Delta W_j = 0$) |
| **Pipe Network** | Communication topology (e.g. small-world, ring, grid) |
| **Fluid Delay / Head Loss** | Asynchronous staleness decay multiplier |

---

## Mathematical Formulation

1. **Hydraulic Pressure**:
   $$P_{ij} = \frac{\|W_i - W_j\|_2}{R_{ij}}$$

2. **Adaptive Flow Coefficient**:
   $$\eta_{ij} = \text{clip}\left(\gamma \cdot P_{ij}, \, 0, \, \eta_{\max}\right)$$

3. **Symmetric Parameter Conservation**:
   $$\Delta W = \eta_{ij} \cdot (W_j - W_i)$$
   $$W_i \leftarrow W_i + \Delta W$$
   $$W_j \leftarrow W_j - \Delta W$$

4. **Asynchronous Staleness Attenuation**:
   $$\text{multiplier} = \frac{1}{1 + \beta \cdot \max(0, v_{\text{current}} - v_{\text{update}})}$$
   $$\eta_{\text{scaled}} = \eta_{ij} \cdot \text{multiplier}$$

---

## Installation

Install in editable development mode:
```bash
git clone https://github.com/Soundarya-2004/Hydrofed-ICAF-Pypi.git
cd Hydrofed-ICAF-Pypi
pip install -e ".[test,examples]"
```

---

## Quickstart API

```python
import torch
import torch.nn as nn
from hydrofed import HydroFed, HydroFedConfig, HydroFedNode

# 1. Define any parameterized model
model_fn = lambda: nn.Sequential(nn.Linear(10, 20), nn.ReLU(), nn.Linear(20, 2))

# 2. Configure HydroFed (supports 1 to 60 clients)
config = HydroFedConfig(
    num_clients=10,
    topology="small_world",
    asynchronous=True,
    enable_encryption=True,
    rounds=5,
    seed=42,
)

# 3. Create simulated client nodes
clients = [HydroFedNode(client_id=i, model=model_fn()) for i in range(10)]

# 4. Initialize engine and run federated consensus
fed = HydroFed(config=config)
fed.register_clients(clients)
summary = fed.fit()

print(f"Final Consensus Error: {summary['final_consensus_error']:.6f}")
print(f"Total Bytes Transmitted: {summary['total_bytes_transmitted']} bytes")
```

---

## Client Capacity: Why 60 Simulated Clients?

HydroFed officially supports **1 to 60 simulated clients** (`MAX_CLIENTS = 60`).

```python
# Values above 60 are strictly rejected:
config = HydroFedConfig(num_clients=61)
# Raises: ValueError: "Maximum supported client count is 60."
```

> **Note**: 60 clients is the maximum supported configuration of this framework release and represents the primary experimental benchmark configuration used by the associated research project to evaluate decentralized consensus, non-IID Dirichlet distributions, communication behavior, and scalability across simulated clinics/clients. It is **not** a mathematical limitation of the HydroFed consensus mechanism.

---

## Examples

HydroFed includes three complete, runnable examples:

1. **Image Classification (CNN)**:
   ```bash
   python examples/image_classification/train.py
   ```
2. **Tabular Classification (MLP)**:
   ```bash
   python examples/tabular_classification/train.py
   ```
3. **Custom Model & Schema Validation**:
   ```bash
   python examples/custom_model/train.py
   ```

---

## Comprehensive Documentation

- [System Architecture](docs/architecture.md)
- [Mathematical Formulation](docs/mathematics.md)
- [Client Model & Scalability](docs/client_model.md)
- [Consensus Mechanism](docs/consensus.md)
- [Asynchronous Staleness Damping](docs/asynchronous.md)
- [Network Topologies](docs/topology.md)
- [Security & Encryption](docs/security.md)
- [Data Partitioning](docs/partitioning.md)
- [Metrics Specification](docs/metrics.md)
- [Custom Model Integration](docs/custom_models.md)
- [Custom Dataset Integration](docs/custom_datasets.md)
- [Limitations & Boundaries](docs/limitations.md)

---

## Running the Test Suite

Execute the complete test suite with `pytest`:
```bash
pytest
```

Run benchmarks across client scales:
```bash
python benchmarks/run_benchmarks.py
```

---

## Authors & Research Team

| Author | Email | Role |
| :--- | :--- | :--- |
| **Soundarya R** | [soundaryaramachandra2003@gmail.com](mailto:soundaryaramachandra2003@gmail.com) | Core Research & Architecture |
| **Tanmaie P U** | [tanmaiepu@gmail.com](mailto:tanmaiepu@gmail.com) | Research & System Design |
| **Trishika S** | [trishikas295@gmail.com](mailto:trishikas295@gmail.com) | Research & Implementation |
| **Shambhavi E L** | [shambhaviprofile@gmail.com](mailto:shambhaviprofile@gmail.com) | Research & Evaluation |
| **M Sathya** | — | Research Guide |

---

## License
HydroFed is licensed under the [Apache License 2.0](LICENSE).
