Metadata-Version: 2.4
Name: bcfl-optimizer
Version: 0.2.0
Summary: Energy-efficient and latency-aware device selection for Blockchain-Enabled Federated Learning.
Author: Deepali Kushwaha, Manan Kalavadia, Vinayaka Hegde, Om Jee Pandey
License: MIT
Project-URL: Repository, https://github.com/v1nayh3g/bcfl-optimizer
Project-URL: Paper, https://doi.org/10.1109/TCSII.2023.3322340
Keywords: federated-learning,blockchain,edge-computing,optimization
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.23
Provides-Extra: plot
Requires-Dist: matplotlib>=3.4; extra == "plot"
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Dynamic: license-file

# bcfl-optimizer

**Energy-efficient and latency-aware device selection for Blockchain-Enabled Federated Learning.**

Reference implementation of:
> D. Kushwaha, M. Kalavadia, V. Hegde and O. J. Pandey,
> *"Energy-Efficient and Latency-Aware Blockchain-Enabled Federated Learning for Edge Networks,"*
> IEEE Transactions on Circuits and Systems II: Express Briefs, vol. 71, no. 3, pp. 1126–1130, March 2024.
> [doi:10.1109/TCSII.2023.3322340](https://doi.org/10.1109/TCSII.2023.3322340)

Adding a blockchain to federated learning removes the single point of failure of a central
server, but miner verification, block generation and accidental forks add latency and
energy to every round. Given a network of edge devices and miners, this library picks the
subset of devices (and so of miners) that jointly minimizes a round's latency and energy.

## Installation

```bash
pip install bcfl-optimizer          # numpy only
pip install "bcfl-optimizer[plot]"  # + matplotlib, for reproduce/
```

## Quick start

```python
from bcfl import DevicePool, MinerPool, optimize

devices = DevicePool.random(n=50, num_miners=15, seed=0)  # Table I ranges
miners = MinerPool.random(m=15, seed=0)

result = optimize(devices, miners, s_d=30, beta=0.5)
result.selected_devices, result.selected_miners  # S_D, S_M
result.latency, result.energy, result.a_fork     # T, E, A_fork of one round
```

To describe your own network, construct `DevicePool` and `MinerPool` directly; each field
is documented in its docstring. Link rates are given in bit/s, and `shannon_rate(bandwidth, snr)`
converts bandwidth and SNR to a rate.

## What is implemented

| Paper | Code |
|---|---|
| Eq. (2) local computation | `DevicePool.computation_cost` |
| Eq. (3) upload, Eq. (8) download | `DevicePool.upload_cost`, `DevicePool.download_cost` |
| Eqs. (4)–(5) cross-verification, including queuing delay | `optimizer._verification_time`, `round_cost` |
| Eq. (7) block propagation | `optimizer._miner_set_cost` |
| Eq. (9) round latency T and energy E | `round_cost` |
| Eq. (10) forking probability and A_fork | `forking_probability`, `forking_multiplier` |
| Eq. (11) objective, Algorithm 1 | `optimize` |

`optimize` follows Algorithm 1. Phase 1 enumerates the miner sets with minimum A_fork that
can host S_D devices. Phase 2 (the paper's tree search) is an exact branch-and-bound:
T and E never decrease when a device is added, so a partial selection's cost bounds all of
its completions. `tests/test_optimizer.py` checks the result against exhaustive search.

### Modelling choices

Where the paper leaves a detail open, the implementation follows the simulation that
produced its figures:

- **A_fork is a whole number of block-generation attempts:** `ceil(1 / (1 - p_fork))`.
- **E[t_bg] = 1 / (λ |S_M|)**, the expected time for the first of |S_M| miners to find a block.
- **The block is propagated by the selected miner with the fastest verification** (smallest τ^comp).
- **Every selected miner hosts at least one selected device**, so S_M is exactly the set of miners associated with S_D.
- **`DevicePool.random` and `MinerPool.random` sample the simulation's ranges:**
  - powers of 20–30 dBm (devices) and 25–30 dBm (miners);
  - Rayleigh-faded channel gains, 2.5·10⁻⁵·Exp(1) for device links and 10⁻⁵·Exp(1) between miners;
  - τ^comp of 2–2.5 ms, P^ver of 0.3–0.5 W, P_bg of 0.5–1 W;
  - model and block sizes of 0.5–1·10⁶ bits.

## Reproducing the paper

`reproduce/parameters.json` holds the exact parameters of the simulation behind Figs. 3–4
(N_D = 50 devices, N_M ∈ {15, 20, 25} miners). `reproduce/original_selections.json` holds the
selections that simulation recorded.

```bash
python reproduce/reproduce.py --plot   # ~2 min; writes reproduce/fig3.png
```

![Latency, energy and selected miners vs. S_D](reproduce/fig3.png)

- **Selected miners and A_fork:** for all 30 settings (N_M ∈ {15, 20, 25} × S_D ∈ {5, …, 50}), the
  number of selected miners and A_fork equal the original simulation's.
- **Energy:** between −2% and +16% of the original (median +3%).
- **Latency:** 5–50% higher, because this implementation includes the verification queuing
  delay of Eqs. (4)–(5), which the original simulation did not model.
- **Selected devices:** the miner sets and A_fork agree, but the chosen devices within them
  can differ. The objective now includes the queuing delay, and it is Eq. (11) exactly.

| N_M = 15, 80% of devices vs. all devices | paper | this implementation |
|---|---|---|
| forking events | −66.67% | −66.67% |
| latency | −66.30% | −61.77% |
| energy | −82.19% | −81.76% |

## Federated training with Flower

A [Flower](https://flower.ai) baseline that uses this selection inside federated training
on Google Speech Commands is proposed in
[flwrlabs/flower#6799](https://github.com/flwrlabs/flower/issues/6799).

## Development

```bash
pip install -e ".[test,plot]"
pytest
```

## Citation

```bibtex
@article{kushwaha2024energy,
  title   = {Energy-Efficient and Latency-Aware Blockchain-Enabled Federated Learning for Edge Networks},
  author  = {Kushwaha, Deepali and Kalavadia, Manan and Hegde, Vinayaka and Pandey, Om Jee},
  journal = {IEEE Transactions on Circuits and Systems II: Express Briefs},
  volume  = {71},
  number  = {3},
  pages   = {1126--1130},
  year    = {2024},
  doi     = {10.1109/TCSII.2023.3322340}
}
```

## License

MIT License. See [LICENSE](LICENSE).
