Federated Learning System

A scalable, fault-tolerant Federated Learning implementation using Flower framework. Designed to support 10+ concurrent clients with comprehensive error handling, configuration management, and monitoring.

Quick Start • Documentation • Installation • Contributing

Features

✅ Scalability

Supports 10+ concurrent clients
Configurable client/server parameters
Efficient data partitioning
Load-balanced communication

✅ Reliability

Automatic client reconnection with exponential backoff
Comprehensive error handling
Resource cleanup and management
Connection timeout handling

✅ Configuration

Environment variable support
Per-component configuration classes
Default sensible values
Easy distributed setup

✅ Monitoring & Logging

Structured logging with rotation
Per-client and per-round logging
Metrics aggregation and tracking
Performance statistics

✅ Production Ready

Type hints throughout
Docstring documentation
Exception hierarchy
Best practices implementation

Architecture

┌─────────────────────────────────────────────────────────┐
│                    Federated Server                     │
│        (Aggregation, Strategy, Metrics Tracking)        │
└──────────────┬────────────────────────────────────────── │
               │
      ┌────────┴────────┬──────────────┬──────────────┐
      │                 │              │              │
   Client 0          Client 1      Client 2  ...  Client N
   (MNIST)           (MNIST)       (MNIST)         (MNIST)

Installation

Clone Repository

git clone https://github.com/YOUR_USERNAME/federated-learning-system.git
cd federated-learning-system

Prerequisites

Python 3.10+
CUDA 11.8+ (optional, for GPU support)

Setup

# Clone or download the project
cd /path/to/project

# Create virtual environment
python -m venv venv

# Activate virtual environment
# On Windows:
venv\Scripts\activate
# On Linux/Mac:
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# For GPU support (optional)
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

Quick Start

1. Start the Server

# Terminal 1: Start the federated learning server
python server.py

Expected output:

2024-01-10 14:30:45 [INFO    ] federated_learning - Starting Flower Server...
2024-01-10 14:30:45 [INFO    ] federated_learning -   Address: 0.0.0.0:8080
2024-01-10 14:30:45 [INFO    ] federated_learning -   Rounds: 5

2. Start Clients

# Terminal 2: Start client 0
python client.py --partition-id 0 --num-partitions 3

# Terminal 3: Start client 1
python client.py --partition-id 1 --num-partitions 3

# Terminal 4: Start client 2
python client.py --partition-id 2 --num-partitions 3

3. Monitor Training

The server will automatically start training once minimum clients are connected:

2024-01-10 14:31:20 [INFO    ] federated_learning - Round 1: Training completed...
2024-01-10 14:31:40 [INFO    ] federated_learning - ROUND 1 EVALUATION RESULTS
                                Loss      : 0.3245
                                Accuracy  : 0.9145 (91.45%)
                                Clients   : 3

Configuration

Environment Variables

Create a .env file in the project root:

# Server Configuration
SERVER_HOST=0.0.0.0
SERVER_PORT=8080
NUM_ROUNDS=5
MIN_FIT_CLIENTS=2
MIN_EVALUATE_CLIENTS=2
MIN_AVAILABLE_CLIENTS=2
SERVER_TIMEOUT=600

# Client Configuration
SERVER_HOST=127.0.0.1
SERVER_PORT=8080
BATCH_SIZE=64
NUM_WORKERS=2
DEVICE=auto
RETRY_ATTEMPTS=3
RETRY_DELAY=5

# Data Configuration
DATASET_PATH=./data
SHUFFLE=true
PIN_MEMORY=true

# Training Configuration
EPOCHS_PER_ROUND=1
LEARNING_RATE=1.0
OPTIMIZER=Adadelta
WEIGHT_DECAY=0.0

Command-Line Arguments

Server

python server.py

Environment variables control all server settings.

Client

python client.py \
  --partition-id 0 \
  --num-partitions 10 \
  --server 192.168.1.100:8080 \
  --batch-size 32 \
  --num-workers 4 \
  --log-level DEBUG \
  --log-file logs/client_0.log

Options:

--partition-id: Client ID (required)
--num-partitions: Total clients (default: 10)
--server: Server address (default: 127.0.0.1:8080)
--batch-size: Training batch size (default: 64)
--num-workers: Data loading workers (default: 2)
--log-level: DEBUG|INFO|WARNING|ERROR|CRITICAL (default: INFO)
--log-file: Log file path (optional)

Scaling to 10+ Clients

Single Machine (Testing)

# Terminal 1: Server
python server.py

# Terminal 2-11: Clients (10 clients)
for i in {0..9}; do
  gnome-terminal -- python client.py --partition-id $i --num-partitions 10
done

Distributed Setup

Server Machine:

# Set SERVER_HOST to machine IP (e.g., 192.168.1.100)
export SERVER_HOST=0.0.0.0
python server.py

Client Machines:

# For each client machine
export SERVER_HOST=192.168.1.100  # Server IP
python client.py \
  --partition-id $CLIENT_ID \
  --num-partitions 10

Performance Tuning

For 10+ clients:

# Server settings (.env)
MIN_AVAILABLE_CLIENTS=10
MIN_FIT_CLIENTS=8
MIN_EVALUATE_CLIENTS=8
SERVER_TIMEOUT=1200

# Client settings
BATCH_SIZE=32
NUM_WORKERS=4
RETRY_ATTEMPTS=5
RETRY_DELAY=10

Project Structure

project/
├── client.py              # Production client with error handling
├── server.py              # Production server with aggregation
├── model.py               # Neural network model
├── utils.py               # Data loading and training utilities
├── config.py              # Centralized configuration management
├── logger.py              # Logging configuration
├── exceptions.py          # Custom exception hierarchy
├── requirements.txt       # Python dependencies
├── .env.example           # Environment template
├── README.md              # This file
└── logs/                  # Generated log files
    ├── server.log
    ├── client_0.log
    └── client_1.log

Error Handling

The system handles common errors:

Client Errors

Error	Cause	Resolution
`ConnectionError`	Cannot reach server	Check server is running and address is correct
`DataLoadingError`	Dataset download failed	Check internet connection and disk space
`DeviceError`	GPU initialization failed	Falls back to CPU automatically
`TrainingError`	Training failed	Check model and data
`TimeoutError`	Operation took too long	Increase `SERVER_TIMEOUT`

Server Errors

Error	Cause	Resolution
`ServerError`	Aggregation failed	Check client data validity
`ConfigurationError`	Invalid config	Verify parameters match clients

All errors are logged with full stack traces in log files.

Logging

Log Levels

DEBUG: Detailed internal state
INFO: Training progress and key events
WARNING: Recoverable issues
ERROR: Failures requiring intervention
CRITICAL: System-wide failures

Log Files

# Server logs
tail -f logs/server.log

# Client logs
tail -f logs/client_0.log

# Watch all logs
tail -f logs/*.log

Monitoring Metrics

The server tracks and reports:

Per-Round Metrics
- Aggregated loss
- Aggregated accuracy
- Number of participating clients
- Failure count
Overall Statistics
- Best accuracy achieved
- Best round
- Training time

================================================================================
ROUND 1: Training completed with 10 clients (0 failures)
================================================================================
Loss      : 0.5342
Accuracy  : 0.8754 (87.54%)
Clients   : 10
================================================================================

Performance

Baseline Metrics (Single GPU, 10 clients)

Per-Round Time: ~30-60 seconds
Throughput: ~600 samples/second
Memory: ~2GB GPU + 500MB per client process

Optimization Tips

Increase batch size for better GPU utilization
Use pin_memory=true for faster data transfer
Reduce num_workers if CPU-bound
Enable mixed precision training (future enhancement)

Troubleshooting

Clients cannot connect to server

# Check server is running
netstat -an | grep 8080

# Check firewall if on different machines
# Linux: sudo ufw allow 8080
# Windows: Check Windows Defender Firewall

Out of memory errors

# Reduce batch size
python client.py --batch-size 32

# Or reduce number of workers
python client.py --num-workers 1

Slow training

# Enable GPU
export CUDA_VISIBLE_DEVICES=0

# Increase batch size
python client.py --batch-size 128

# Reduce epochs per round (in .env)
EPOCHS_PER_ROUND=1

Advanced Usage

Custom Data Partitioning

Edit utils.load_data() to implement custom partitioning strategy.

Custom Model Architecture

Edit model.Net class with your architecture.

Custom Training Algorithm

Extend CustomFedAvg in server.py to implement custom aggregation.

Testing

# Run unit tests
pytest tests/ -v

# With coverage
pytest tests/ --cov=. --cov-report=html

Security Considerations

For production:

Enable SSL/TLS for client-server communication
Add authentication for client identity verification
Encrypt model parameters in transit
Implement differential privacy for sensitive data
Add rate limiting on server

Contributing

We welcome contributions! Please follow these guidelines:

Code Style

Format Code: Use Black formatter
```
black *.py
```
Lint Code: Use Flake8
```
flake8 *.py
```
Type Checking: Use mypy
```
mypy *.py
```
Requirements:
- Follow PEP 8 style guide
- Add type hints to all functions
- Include comprehensive docstrings
- Add unit tests for new features

Steps to Contribute

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Run tests and formatters
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

MIT License - for details, see the LICENSE file

Support

For issues and questions:

Check logs for detailed error messages
Ensure all dependencies are installed: pip install -r requirements.txt
Verify configuration in .env file
Try with minimum setup (1-2 clients) first
Open an Issue on GitHub

Name		Name	Last commit message	Last commit date
md		md
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
client.py		client.py
config.py		config.py
exceptions.py		exceptions.py
health_check.py		health_check.py
logger.py		logger.py
model.py		model.py
requirements.txt		requirements.txt
run_clients.py		run_clients.py
server.py		server.py
test_suite.py		test_suite.py
utils.py		utils.py
verify_data.py		verify_data.py

Latest commit

History

Folders and files

Repository files navigation