ARENA Score
ARENA Score (Adaptive Review and Evaluation using Novel Aggregation Score) is a novel client evaluation and weighted aggregation algorithm for Federated Learning.
🎯 Key Features
- Adaptive Client Evaluation: Dynamically assesses client update quality using multiple metrics
- Robust Aggregation: Filters out unreliable/malicious client contributions
- Anomaly Detection: Detects Byzantine clients using KL divergence and cosine similarity
- Gradient Recycling: Maintains momentum by reusing successful updates from missing clients
- Model Agnostic: Works with any model that implements the simple weight interface
📊 ARENA Score Formula
S_j = α(t) × max(0, ΔAcc_j) + γ(t) × CS_j + η × SN_j/(1 + SN_j)
Where:
- ΔAcc - Local accuracy improvement
- CS - Cosine similarity between client update and global direction
- SN - Spectral norm:
log(1 + σ_max(W_j)) - α(t), γ(t) - Adaptive time-varying weights
🚀 Installation
pip install arena-score
For Numba acceleration (optional):
pip install arena-score[accelerate]
📝 Quick Start
from arena_score import ARENAScoreClient, ARENAScoreServer, run_arena_score
# Create clients with your model
clients = [
ARENAScoreClient(
client_id=i,
model=your_model.copy(), # Model with get_weights/set_weights
X=X_train[i],
y=y_train[i],
local_epochs=5,
batch_size=32
)
for i in range(n_clients)
]
# Run ARENA Score federated learning
history = run_arena_score(
global_model=your_model,
clients=clients,
n_rounds=10,
eval_data=(X_test, y_test)
)
print(f"Final accuracy: {history['test_accuracy'][-1]:.4f}")
🔧 Advanced Usage
Custom Server Configuration
from arena_score import ARENAScoreServer
server = ARENAScoreServer(
global_model=model,
alpha_0=0.7, # Initial accuracy weight
alpha_min=0.3, # Minimum accuracy weight
gamma_0=0.3, # Initial cosine similarity weight
gamma_min=0.5, # Minimum cosine similarity weight
eta=0.5, # Spectral norm coefficient
lambda_decay=0.1, # Decay rate for adaptive weights
anomaly_threshold=-0.5, # CS threshold for anomaly detection
kl_threshold=0.5, # KL divergence threshold
enable_gradient_recycling=True
)
Computing ARENA Score Directly
from arena_score import compute_arena_score
score = compute_arena_score(
delta_acc=0.05, # Accuracy improvement
cosine_sim=0.8, # Cosine similarity
spectral_norm=2.5, # Spectral norm
alpha_t=0.5, # Current alpha weight
gamma_t=0.4 # Current gamma weight
)
Utility Functions
from arena_score import (
compute_cosine_similarity,
compute_spectral_norm,
compute_kl_divergence,
flatten_weights,
unflatten_weights
)
# Compute cosine similarity between weight vectors
cs = compute_cosine_similarity(weights_a, weights_b)
# Compute spectral norm of weights
sn = compute_spectral_norm(weights_dict)
📈 Model Interface
Your model must implement these methods:
class YourModel:
def get_weights(self) -> Dict[str, np.ndarray]:
"""Return model weights as a dictionary."""
pass
def set_weights(self, weights: Dict[str, np.ndarray]):
"""Set model weights from a dictionary."""
pass
def forward(self, X: np.ndarray) -> np.ndarray:
"""Forward pass, returns predictions."""
pass
def backward(self, X, y, y_pred) -> Dict[str, np.ndarray]:
"""Backward pass, returns gradients."""
pass
def update_weights(self, gradients: Dict[str, np.ndarray]):
"""Update weights using gradients."""
pass
def predict(self, X: np.ndarray) -> np.ndarray:
"""Make predictions (0/1 for classification)."""
pass
def predict_proba(self, X: np.ndarray) -> np.ndarray:
"""Return probability predictions."""
pass
def copy(self) -> 'YourModel':
"""Return a deep copy of the model."""
pass
📜 License
MIT License - see LICENSE for details.
Metadata
Release files for arena-score 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| arena_score-1.0.0.tar.gz | 13.1 kB | Without provenance | Details for arena_score-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| arena_score-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for arena_score-1.0.0-py3-none-any.whl |
Total release size: 29.0 kB
Release files / arena_score-1.0.0.tar.gz
| Download URL | arena_score-1.0.0.tar.gz |
|---|---|
| Size | 13.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ef9d0744b4a05efbd27aa5a15650484b9b7c4664fe0661d29876cdfdfd0eff02
|
|
BLAKE2b-256 checksum How to use checksums |
e560e16f6c44380118ed1aee91297953c72d8192a8686f593adc3d8771d0b9bb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.3
|
Release files / arena_score-1.0.0-py3-none-any.whl
| Download URL | arena_score-1.0.0-py3-none-any.whl |
|---|---|
| Size | 15.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0518b02d7df8da202f04b2998c9d6e9207668812d998f614bebdf20e9c5639fe
|
|
BLAKE2b-256 checksum How to use checksums |
d58f2a8ab341f816b79e9dd44a2859e56423e8312d3d0d674f0fd706674a7c8b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.3
|
Security for arena-score 1.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.