SimQFL: Quantum Federated Learning Simulator

• SimQFL is a software platform for simulating quantum federated learning that combines quantum circuit modeling with classical orchestration.
• It enables end-to-end QFL experiments by integrating parameterized circuit design, gradient-based optimization, noise modeling, and federated aggregation.
• The platform offers real-time visualization and customizable hyperparameters to facilitate algorithm benchmarking and rapid prototyping for distributed quantum ML.

SimQFL is a software platform specifically designed for simulating, analyzing, and visualizing quantum federated learning (QFL) protocols in a classical computing environment. Unlike general-purpose quantum circuit simulators and classical federated learning (FL) toolkits, SimQFL provides integrated support for all core phases of distributed quantum neural network (QNN) training—including parameterized circuit modeling, input encoding, gradient-based optimization, noise modeling, and client–server communication—while also supplying real-time, user-friendly visualization of learning metrics at each epoch. SimQFL enables customizable experimentation and reduces the barrier to entry for QFL research by giving researchers granular control over quantum and classical hyperparameters and an interactive GUI for monitoring, tuning, and exporting models and results (Rahman et al., 17 Aug 2025).

1. System Architecture and Core Components

SimQFL adopts a federated server–client architecture. The system consists of a single ClassicalServer that orchestrates $R$ rounds of communication among $N$ QuantumClient nodes. Each QuantumClient $n$ possesses a private dataset $D_n$, encodes its minibatch inputs into a $Q_n$-qubit quantum state, applies a parameterized quantum circuit (PQC), and returns updated parameters to the server. The orchestration, communication, and aggregation all occur on classical hardware, using state-vector emulation for quantum operations.

Major software modules are organized as follows:

• QuantumEncoder: Transforms a classical vector $w \in \mathbb{R}^d$ into a normalized quantum state using amplitude encoding:

$$|\psi_{\text{enc}}(w)\rangle = \sum_{i=0}^{2^Q-1} \frac{w_i}{\|w\|} |i\rangle.$$

Deployed as a reusable Python class.

• QuantumModel (Circuit Builder): Specifies the PQC ansatz $U(\theta)$ over $Q$ qubits and $L$ layers. Each layer contains parameterized single-qubit rotations ($N$0, $N$1, $N$2) and fixed CNOT gates. Internally,

$N$3

with $N$4 as Pauli generators.

• FederatedTrainingManager: Handles local training on clients ($N$5 local epochs), gradient estimation via the parameter-shift rule, communication, and global aggregation following quantum-aware federated averaging.
• Aggregator: On the server, collects all $N$6, computes a weighted average, and broadcasts updated global parameters.
• CommunicationLayer: Simulates synchronous communication between server and clients.
• VisualizationEngine: Real-time display implemented with Flask and JavaScript, updating charts for global/test accuracy, per-client losses, and fidelity after every epoch (Rahman et al., 17 Aug 2025).

2. Quantum Federated Learning Algorithms Implemented

SimQFL implements a quantum extension of Federated Averaging (“FedAvgQ”). Each QuantumClient executes $N$7 steps of local optimization on circuit parameters, then synchronously shares the optimized weights with the server. The server aggregates parameters and iterates.

• Parameterized PQC Form: For $N$8:

$N$9

or equivalently as a product of unitary rotations as above.

• Local Loss and Gradient: For a client $n$0 with batch $n$1,

$n$2

with $n$3 and $n$4 e.g. cross-entropy. Gradients are computed by parameter-shift:

$n$5

• Server Aggregation:

$n$6

Users may substitute aggregation or optimization routines (e.g., robust FL) as required (Rahman et al., 17 Aug 2025).

3. Simulation Environment and Configuration Parameters

SimQFL provides extensive configurability of both quantum and classical FL hyperparameters:

• Quantum Hyperparameters:
  • Qubits per client ($n$7, range 1–10)
  • Circuit depth ($n$8)
  • Allowed gates: $n$9, $D_n$0, $D_n$1, CNOT
  • Measurement: expectation vs. sample-based
• Classical Hyperparameters:
  • Number of global rounds ($D_n$2), local epochs ($D_n$3), batch size, learning rate ($D_n$4)
  • Number of clients ($D_n$5, up to 100)
  • Optimizer (Adam, SGD, RMSProp, etc.)
• Noise and Decoherence: Optional NoiseModel submodule:
  • Depolarizing channel: $D_n$6
  • Amplitude damping: $D_n$7, with $D_n$8 and $D_n$9 as specified Kraus operators
  • Tunable $Q_n$0 or $Q_n$1 for noise rates

Custom datasets can be uploaded in CSV; drag-and-drop support for images is included (Rahman et al., 17 Aug 2025).

4. Real-Time Visualization and User Interface Features

SimQFL includes a browser-based dashboard for epoch-wise monitoring:

• Live updates per global round: global accuracy/loss, per-client loss curves, and quantum fidelity ($Q_n$2 if enabled).
• Interface elements:
  • Training vs. test charts (accuracy/loss by round)
  • Per-client loss heatmap
  • Fidelity visualizations
  • Hyperparameter summary and adjustment widgets
  • Dataset upload and image loader panels
  • Export buttons for model weights, logs, figures

A WebSocket/HTTP polling mechanism provides immediate feedback, supporting interactive debugging, rapid convergence analysis, and dynamic simulation configuration (Rahman et al., 17 Aug 2025).

5. Benchmarking, Evaluation Metrics, and Comparative Analysis

SimQFL's default benchmarking suite includes MNIST, Fashion-MNIST, and CIFAR-100. Performance metrics are as follows:

• Final accuracy (e.g., MNIST QFL $Q_n$3 vs. classical FL $Q_n$4)
• Convergence speed (number of rounds to reach target; e.g., QFL converges in $Q_n$5 rounds vs. classical in $Q_n$6)
• Communication overhead (number of floating-point parameters times rounds)

Compared to existing tools such as QuNetSim (focused solely on quantum network simulation) and OpenFL/PeerFL (classical FL only), SimQFL is distinctive in its combined support for PQC modeling, complete QNN training, and federated protocols. QFL models trained with SimQFL have demonstrated up to $Q_n$7 accuracy improvements over classical MLPs on image classification tasks, with only modest communication cost per client and round (Rahman et al., 17 Aug 2025).

6. Practical Use Cases and Extensibility

SimQFL is intended as a research and development platform for distributed QNN design and quantum networking studies. Typical workflows involve:

1. Launching the simulation via app.py and browser dashboard
2. Configuring quantum/classical parameters, uploading datasets or selecting from built-in tasks
3. Executing QFL runs while monitoring real-time charts
4. Interactively adjusting hyperparameters or noise models during or between rounds
5. Exporting trained weights and logs for post-processing or further analysis with tools such as Qiskit or Pennylane

The platform is extensible: users may augment the QuantumEncoder class (for new encodings), add deeper circuit layers (noting “barren plateau” effects), implement novel aggregation rules (e.g., sparse FL, FedProx), or target hardware-specific noise by tuning the NoiseModel (Rahman et al., 17 Aug 2025).

---

SimQFL establishes an end-to-end, fully configurable environment for QFL simulation and analysis, uniquely bridging the gap between quantum neural network design, distributed ML experimentation, and user-centric visualization. It serves as a practical resource for rapid algorithmic prototyping, comparative experimentation with classical vs. quantum federated paradigms, and foundational exploration of privacy-preserving distributed quantum ML architectures prior to the widespread availability of large-scale quantum network hardware (Rahman et al., 17 Aug 2025).