fairswarm 0.5.0

Provably fair particle swarm optimization for federated learning coalition selection

FairSwarm

Provably fair particle swarm optimization for federated learning coalition selection

Overview

FairSwarm is a novel particle swarm optimization algorithm designed for fair client selection in federated learning. It provides provable guarantees on both convergence and demographic fairness.

Key Innovation

FairSwarm introduces a fairness-aware velocity update that steers optimization toward demographically balanced coalitions:

v = ω·v + c₁·r₁·(pBest - x) + c₂·r₂·(gBest - x) + c₃·∇_fair
                                                    ^^^^^^^^
                                                    Novel fairness gradient

Theoretical Guarantees

Theorem	Guarantee
Theorem 1	Convergence to stationary point with probability 1
Theorem 2	ε-fairness: DemDiv(S*) ≤ ε with high probability
Theorem 3	(1-1/e-η) approximation for submodular objectives
Theorem 4	Privacy-fairness tradeoff lower bound

Data Access and Compliance

This library contains no patient data. Examples and tests use only synthetic data generated by create_synthetic_clients().

Experiments on restricted clinical datasets (MIMIC-III, eICU-CRD) require that you independently obtain credentialed access:

1. Complete CITI "Data or Specimens Only Research" training.
2. Sign the PhysioNet Data Use Agreement at https://physionet.org/about/database/.
3. Download MIMIC-III / eICU under your own credentials.
4. Place derived cohort files outside the repository tree, or in a path covered by .gitignore (data/processed/, data/raw/).
5. Set the MIMIC_DATA_PATH (or EICU_DATA_PATH) environment variable to point the experiment scripts at your local data.

Do NOT commit, redistribute, or share patient-level data in any form. You are solely responsible for compliance with the PhysioNet DUA, HIPAA, and your institution's IRB requirements.

The full threat model — what the server sees, what is out of scope (malicious servers, sybil clients, model inversion, side-channel attacks), and how the package's privacy claims align with HIPAA Safe Harbor / GDPR / PhysioNet DUA / All of Us terms — is in THREAT_MODEL.md.

Installation

pip install fairswarm

For development:

pip install fairswarm[dev]

Quick Start

from fairswarm import FairSwarm, FairSwarmConfig, Client
from fairswarm.demographics import DemographicDistribution, CensusTarget
import numpy as np

# Create clients (hospitals) with demographic information
clients = [
    Client(
        id=f"hospital_{i}",
        demographics=np.random.dirichlet([2, 2, 2, 2]),
        dataset_size=1000 + i * 100,
    )
    for i in range(20)
]

# Configure the optimizer
config = FairSwarmConfig(
    swarm_size=30,
    max_iterations=100,
    coalition_size=10,
    fairness_weight=0.3,  # λ in fitness function
    seed=42,
)

# Create target demographics (e.g., US Census 2020)
target = DemographicDistribution.from_dict({
    "white": 0.576,
    "black": 0.124,
    "hispanic": 0.187,
    "asian": 0.061,
    "other": 0.052,
})

# Run optimization
optimizer = FairSwarm(
    clients=clients,
    coalition_size=10,
    target_demographics=target,
    config=config,
)
# Use built-in demographic fitness (or supply your own callable)
from fairswarm.fitness import DemographicFitness
fitness_fn = DemographicFitness(target=target)

result = optimizer.optimize(fitness_fn)

# Check results
print(f"Selected coalition: {result.coalition}")
print(f"Fitness: {result.fitness:.4f}")
print(f"ε-fair: {result.is_epsilon_fair(0.05)}")

Documentation

Full API documentation is available in the source code docstrings. For the formal algorithm specification, theoretical proofs, and experimental methodology, please refer to:

T. Norwood, D. Das, P. Chatterjee, E. Bentley, and U. Ghosh, "FairSwarm: Trustworthy Coalition Selection for Fair and Secure Federated Intelligence," IEEE Trans. Consum. Electron., 2026. note : Submitted

Citation

If you use this library or its results, please cite the article (preferred — the one that carries the formal theorems) and, if relevant, the specific software release.

@article{norwood2026fairswarm,
  title   = {FairSwarm: Trustworthy Coalition Selection for Fair
             and Secure Federated Intelligence},
  author  = {Norwood, Tenicka and Das, D. and Chatterjee, P. and
             Bentley, E. and Ghosh, U.},
  journal = {IEEE Transactions on Consumer Electronics},
  year    = {2026},
  note    = {Submitted}
}

CITATION.cff backs GitHub's "Cite this repository" button and points at the same record.

License

This project is licensed under the PolyForm Noncommercial License 1.0.0. You are free to use, modify, and distribute it for any noncommercial purpose, including academic research, education, and personal projects.

Commercial licensing is available. For commercial use inquiries, please contact Tenicka Norwood.

See LICENSE for full terms.