Metadata-Version: 2.4
Name: bcfl-optimizer
Version: 0.1.0
Summary: Energy-efficient and latency-aware device selection for Blockchain-Enabled Federated Learning.
Author: Vinay
License: MIT
Project-URL: Repository, https://github.com/your-username/bcfl-optimizer
Project-URL: Paper, https://ieeexplore.ieee.org/document/10388123
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.21
Provides-Extra: csv
Requires-Dist: pandas>=1.3; extra == "csv"
Provides-Extra: plot
Requires-Dist: matplotlib>=3.4; extra == "plot"
Provides-Extra: flower
Requires-Dist: flwr>=1.0; extra == "flower"
Provides-Extra: all
Requires-Dist: pandas>=1.3; extra == "all"
Requires-Dist: matplotlib>=3.4; extra == "all"
Requires-Dist: flwr>=1.0; extra == "all"
Dynamic: license-file

# bcfl-optimizer

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

A Python library implementing the joint optimization algorithm from:

> D. Kushwaha, S. Redhu, C. G. Brinton, and R. M. Hegde,  
> *"Energy-Efficient and Latency-Aware Blockchain-Enabled Federated Learning for Edge Networks,"*  
> IEEE TCAS-II, Vol. 71, No. 3, March 2024.

---

## Installation

```bash
pip install -e .
```

**Dependencies:** `numpy` (required), `pandas` (for CSV loading), `matplotlib` (for plotting examples).

## Quick Start

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

# Create pools (from arrays, CSV, JSON, or random)
devices = DevicePool.random(n=50)
miners  = MinerPool.random(m=15)

# Select optimal 30 devices + miners (balanced latency-energy trade-off)
result = optimize(devices, miners, s_d=30, beta=0.5)

print(result)
# OptimizationResult(
#   devices=30, miners=2,
#   latency=3.2145s, energy=12.4532J,
#   fitness=0.012345, a_fork=1.2214, beta=0.5
# )
```

## Loading Real Device Data

```python
# From CSV
devices = DevicePool.from_csv("my_devices.csv")
# Expected columns: cpu_freq, tx_power, data_size

# From JSON
devices = DevicePool.from_json("my_devices.json")

# From NumPy arrays
devices = DevicePool(
    cpu_freq=[1.8e9, 1.2e9, ...],
    tx_power=[0.3, 0.15, ...],
    data_size=[87, 112, ...]
)
```

## API Reference

### `DevicePool(cpu_freq, tx_power, data_size, ...)`
Heterogeneous edge device pool. Methods:
- `.computation_cost(epochs, kappa)` → latency, energy per device (Eq. 1-2)
- `.upload_cost(model_size, bandwidth, noise_power)` → latency, energy (Eq. 3)
- `.total_cost(...)` → combined per-device costs

### `MinerPool(proc_freq, ver_power)`
Miner pool. Methods:
- `.verification_cost(model_size)` → latency, energy per miner (Eq. 4)

### `optimize(device_pool, miner_pool, s_d, beta=0.5, ...)`
Run Algorithm 1 to find optimal device-miner selection.  
Returns `OptimizationResult` with selected indices, latency, energy, fitness.

### `sweep(device_pool, miner_pool, beta=0.5, s_d_range=None, ...)`
Run optimization across multiple S_D values for parameter studies.

### `forking_probability(num_miners, ...)` / `forking_multiplier(...)`
Blockchain forking model (Eq. 10).

## Examples

```bash
python examples/quickstart.py           # Minimal usage
python examples/paper_reproduction.py   # Reproduce Fig. 3 trade-off curves
```

## Citation

If you use this library in your research, please cite:

```bibtex
@article{kushwaha2024energy,
  title   = {Energy-Efficient and Latency-Aware Blockchain-Enabled Federated Learning for Edge Networks},
  author  = {Kushwaha, Deepali and Redhu, Surender and Brinton, Christopher G. and Hegde, Rajesh M.},
  journal = {IEEE Transactions on Circuits and Systems II: Express Briefs},
  volume  = {71},
  number  = {3},
  pages   = {1126--1130},
  year    = {2024}
}
```

## License

MIT License. See [LICENSE](LICENSE).
