Royal Flush Lab

Royal Flush Lab is the deterministic single-machine experimental variant of Royal Flush. It preserves the agent-level semantics of the original Royal Flush platform while providing reproducible scheduling, controlled execution, and consistent resource accounting for algorithm comparison.

Royal Flush Lab is a Python 3.14 command-line platform for running reproducible federated-learning experiments for multi-class classification in a single local process. It supports local and centralized baselines, centralized coordinator-based FL (FedAvg, FedProx), and decentralized Consensus-learning and Consensus-weighted learning families, including synchronous, asynchronous, and coalition-based variants.

Communication and asynchronous execution are simulated with a deterministic discrete-event scheduler; there is no real networking, threading, or uncontrolled concurrency.

Installation

Requires Python 3.14. CUDA acceleration depends on your platform's PyTorch build; see docs/installation.rst for CPU/CUDA-specific guidance.

python -m pip install royalflushlab

To work on Royal Flush Lab itself (tests, linting, docs), install from a clone in editable mode instead:

python -m pip install -e '.[dev,docs]'

Quickstart

royalflushlab init
royalflushlab expand --grid experiment_grid.yml
royalflushlab run --queue queue
royalflushlab analyze --project <project_name>

rfl is an alias for royalflushlab.

See docs/ for the full documentation, including the CLI reference, configuration schemas, algorithm pages, artifact schemas, and analysis methodology.