EcoFL

EcoFL (Energy-Conscious Federated Learning) is an open-source Python framework for reproducible benchmarking of energy-aware federated learning in resource-constrained IoT edge environments.

EcoFL combines synthetic IoT telemetry generation, non-IID client partitioning, lightweight machine learning models, FedAvg-based federated training, adaptive energy-aware scheduling, system-level profiling, and JSON/CSV-ready benchmark outputs. It is designed as a reusable research software artifact for studying the trade-offs between predictive performance, estimated computational energy, communication overhead, latency, and resource usage in edge intelligence.

Scientific motivation

Federated learning enables collaborative model training without centralising raw data, but repeated local training and communication rounds can be expensive for battery-limited edge devices. EcoFL addresses this software gap by providing a compact benchmarking framework that compares centralised learning, standard FedAvg, and an energy-aware federated scheduler under controlled IoT edge constraints.

The framework was developed to support research on sustainable edge AI, low-power machine learning, TinyML-adjacent systems, anomaly detection, and reproducible federated learning experiments.

Main features

• Synthetic multivariate IoT telemetry generator with binary anomaly labels.
• IID and Dirichlet non-IID partitioning for federated clients.
• Lightweight model registry: Logistic Regression, Random Forest, XGBoost, MLP, and Isolation Forest.
• Centralized, FedAvg, and EcoFL energy-aware federated configurations.
• Adaptive client selection based on CPU, RAM, and energy-budget conditions.
• Adaptive early termination based on convergence stagnation.
• System-level profiling using CPU, RAM, latency, communication size, and TDP-based computational energy estimates.
• Command-line interface for quick experiments and reproducibility checks.
• Unit and integration tests for the generator, scheduler, models, server, pipeline, and CLI.
• Documentation and examples for SoftwareX-style reuse.

Installation

git clone https://github.com/TyMill/ecofl.git
cd ecofl
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e .[dev]

Quick start: Python API

from ecofl import BenchmarkPipeline

pipeline = BenchmarkPipeline(
    n_clients=5,
    n_rounds=5,
    n_samples=5_000,
    hardware_profile="raspberry_pi4",
    random_state=42,
    verbose=True,
)

results = pipeline.run_all(model_names=["LogisticRegression", "RandomForest"])
pipeline.save_results("results/quickstart/benchmark_results.json")
pipeline.save_round_history("results/quickstart/round_history.json")

Quick start: CLI

ecofl info

ecofl run \
  --samples 5000 \
  --clients 5 \
  --rounds 5 \
  --models LogisticRegression RandomForest \
  --hardware raspberry_pi4 \
  --output-dir results/cli_run \
  --print-summary

For a deterministic small reproduction run:

ecofl reproduce --quiet

Outputs

EcoFL produces structured JSON files:

• benchmark_results.json — compact per-model/per-configuration summary.
• round_history.json — round-level FL history, including client participation, energy, communication, and predictive metrics.

These outputs are intentionally plain JSON so they can be used from Python, R, notebooks, dashboards, or downstream statistical workflows.

Repository structure

ecofl/
├── ecofl/
│   ├── benchmark/      # BenchmarkPipeline orchestration
│   ├── data/           # Synthetic telemetry and non-IID partitioning
│   ├── energy/         # System monitor and TDP-based energy proxy
│   ├── federated/      # Client, server, FedAvg, EcoFL scheduler
│   ├── models/         # Lightweight model registry and serialization
│   └── cli.py          # Command-line interface
├── docs/               # User and developer documentation
├── examples/           # Minimal reusable examples
├── experiments/        # Publication-scale experiment scripts
├── tests/              # Unit and integration tests
└── results/            # Example/publication results

Testing

EcoFL treats software engineering as part of the scientific contribution. Run:

pytest -q

Optional linting:

ruff check ecofl tests examples

Documentation

Start with:

• docs/installation.md
• docs/quickstart.md
• docs/architecture.md
• docs/cli.md
• docs/api_reference.md
• docs/reproducibility.md
• docs/softwarex_checklist.md

Reproducibility notes

EcoFL uses explicit random seeds for data generation, train/test splitting, non-IID partitioning, and model construction where supported by the underlying libraries. The TDP-based energy model is a reproducible computational energy proxy intended for comparative benchmarking under identical experimental conditions, not a direct hardware power measurement.

Citation

Please cite the repository release and the associated research article when using EcoFL. A CITATION.cff file is included.

License

EcoFL is released under the MIT License. See LICENSE and LICENSE.txt.