docs/plot_convergenvce.md

plot_convergence.py — Analysis and Visualisation Script

This document provides a comprehensive technical reference for plot_convergence.py. This script serves as the primary analytics engine, transforming JSON telemetry logs produced by your execution runner (run_mvp.py) into publication-quality research figures.

Reads accuracy_log.json produced by run_mvp.py and generates three publication-quality figures:

Figure 1 — convergence_plot.png (2 panels)

    Panel 1: Global accuracy over rounds — haflq vs baseline

    Panel 2: Aggregated weight delta Frobenius norm (∣∣ΔW∣∣F​) — haflq vs baseline

Figure 2 — extended_metrics_plot.png (4 panels)

    Panel 1: Per-round communication cost — haflq vs baseline

    Panel 2: Cumulative communication cost — with bandwidth-saved fill

    Panel 3: Parameters discarded per round due to edge transport limits

    Panel 4: Accuracy per MB of communication (efficiency ratio)

Figure 3 — loss_throughput_metrics.png (3 panels)

    Panel 1: Global convergence losses — Training vs. Validation curves

    Panel 2: Per-client loss variance — Visualizing non-IID data distribution trends

    Panel 3: On-device token throughput — Hardware processing speed (tokens/sec)

Every number in every panel comes directly from accuracy_log.json. Nothing is fabricated or randomly generated at the visualization layer.

Usage

Bash

python plot_convergence.py python plot_convergence.py --input path/to/accuracy_log.json python plot_convergence.py --input path/to/log.json --outdir results/plots

Dependencies

Bash

pip install matplotlib numpy

Architectural Overview

The script abstracts the visualization layer from the training loop. It parses empirical telemetry data, applies multi-version schema normalization, isolates system metrics, and generates high-density figures matching academic publication standards. Plaintext

                 ┌────────────────────┐
                 │    run_mvp.py      │
                 └─────────┬──────────┘
                           │
                           ▼ 
               ┌──────────────────────────┐
               │    accuracy_log.json     │
               └────────────┬─────────────┘
                           │
                           ▼ 
               ┌──────────────────────────┐
               │   plot_convergence.py    │
               └───┬──────────┬──────────┬┘
                   │          │          │
   Generates Fig 1 │          │          │ Generates Fig 3
                   ▼          │          ▼
    ┌─────────────────────┐   │   ┌────────────────────────────────┐
    │convergence_plot.png │   │   │  loss_throughput_metrics.png   │
    │─────────────────────│   │   │────────────────────────────────│
    │ 2-Panel Diagnostic  │   │   │ 3-Panel Compute & Loss Matrix  │
    └─────────────────────┘   │   └────────────────────────────────┘
                              ▼ Generates Fig 2
                  ┌───────────────────────────────────┐
                  │    extended_metrics_plot.png      │
                  │───────────────────────────────────│
                  │ 4-Panel Network Efficiency Matrix │
                  └───────────────────────────────────┘

Core Design Goals

Mathematical Invariance: No synthetic, fabricated, or smoothed values are introduced at the plotting layer. Every pixel mapped corresponds strictly to logged telemetry.

Schema Decoupling: Includes structural fallback handlers capable of digesting multi-method cross-comparisons or legacy, single-history array structures without throwing errors.

Production-Grade Aesthetics: Uses a unified hex-color spectrum, proportional axis text offsets, automated tick-overcrowding decimation, and text annotations aligned directly to critical data elements.

Telemetry Schema Specifications

The script expects a structured JSON telemetry payload. It dynamically supports both the production multi-experiment layout and the legacy single-method format. Target Multi-Experiment Schema (Preferred)

This structure maps cross-comparative studies simultaneously (e.g., evaluating your proposed haflq framework directly against standard baseline parameters). JSON

{ "timestamp": "2026-06-23T13:00:00Z", "dataset": "Banking77", "num_rounds": 20, "num_clients": 10, "experiments": { "haflq": [ { "round": 1, "global_accuracy": 0.4521, "total_comm_mb": 8.42, "cumulative_comm_mb": 8.42, "total_discarded_mb": 0.02, "avg_client_accuracy": 0.4110, "update_norm": 4.1251, "train_loss": 2.2145, "val_loss": 2.5102, "token_throughput": 1441.2, "client_1_loss": 2.2510, "client_2_loss": 2.2104, "client_3_loss": 2.1215 }, { "round": 2, "global_accuracy": 0.6285, "total_comm_mb": 6.11, "cumulative_comm_mb": 14.53, "total_discarded_mb": 0.01, "avg_client_accuracy": 0.5942, "update_norm": 4.0912, "train_loss": 1.8841, "val_loss": 2.1154, "token_throughput": 1445.6, "client_1_loss": 1.9214, "client_2_loss": 1.8541, "client_3_loss": 1.8102 } ], "baseline": [ { "round": 1, "global_accuracy": 0.4102, "total_comm_mb": 12.50, "cumulative_comm_mb": 12.50, "total_discarded_mb": 2.15, "avg_client_accuracy": 0.3854, "update_norm": 4.1520, "train_loss": 2.3841, "val_loss": 2.6145, "token_throughput": 1515.4, "client_1_loss": 2.4412, "client_2_loss": 2.3514, "client_3_loss": 2.3145 } ] } }

Legacy Single-Method Schema Support

If the core executor dumps a flat history list representing a single execution pass, the script detects it, logs a structural notice, and auto-wraps the telemetry payload into the standard namespace as haflq. JSON

{ "num_rounds": 20, "history": [ { "round": 1, "global_accuracy": 0.4521, "total_comm_mb": 8.42 } ] }

Visualization Architecture

Figure 1: Convergence Diagnostics (convergence_plot.png)

Dimensions: 14×5.5 inches (Dual-Panel Landscape arrangement).

Target Domain: Standard machine learning training dynamics and model state stabilization metrics.

Panel Metric Rendered Input JSON Keys Analytical Value Panel 1 Global Test Accuracy Convergence global_accuracy Multi-line progression plotting validation accuracy across training iterations. Includes a static horizontal baseline target at 89.13%, serving as a benchmark against top-tier academic reference parameters. Panel 2 Aggregated Weight Delta Norm update_norm Tracks the geometric Frobenius Norm $ Figure 2: Extended Communication Matrix (extended_metrics_plot.png)

Dimensions: 15×11 inches (2×2 Grid Quad-Panel matrix layout).

Target Domain: Systems-level networking efficiency and network-constrained edge resource profiling.

Plaintext

┌──────────────────────────────────────┐──────────────────────────────────────┐ │ [0,0] Per-Round Communication │ [0,1] Cumulative Communication │ │ │ │ │ • Tracks individual round costs │ • Plots total network transfer │ │ • Monitors adaptive compression │ • Shards network bandwidth saved │ └──────────────────────────────────────┘──────────────────────────────────────┘ ┌──────────────────────────────────────┐──────────────────────────────────────┐ │ [1,0] Parameter Discard Profile │ [1,1] Efficiency Ratio Matrix │ │ │ │ │ • Measures drops due to limits │ • Evaluates Accuracy gained per MB │ │ • Proves edge budget compliance │ • The primary optimization target │ └──────────────────────────────────────┘──────────────────────────────────────┘

Panel [0,0] — Per-Round Communication Cost: Plots discrete byte volumes uploaded per epoch. It charts how parameter freezing and quantization steps lower infrastructure costs as training stabilizes.

Panel [0,1] — Cumulative Communication Cost: A continuous step aggregation of overall edge data transfer. If both haflq and baseline modes are present, it renders an alpha-blended teal filling block (#43a2ca) across the curves, computing a vector offset to place an automated arrow annotation detailing the exact volume of Megabytes saved.

Panel [1,0] — Parameters Discarded per Round: Implements an interlaced bar graph matrix visualizing the volume of model layers dropped due to hardware bandwidth limits. Low values in this panel validate the model's adaptive budget alignment.

Panel [1,1] — Communication Efficiency Ratio: Tracks the system's ability to achieve high model utility with a minimal network payload, evaluated via vector conditional logic:
Efficiency=Current Round Transport Burden (MB)Global Accuracy Component​

Figure 3: Compute & Loss Telemetry Matrix (loss_throughput_metrics.png)

Dimensions: 18×5.5 inches (1×3 Panel Landscape arrangement).

Target Domain: Hardware runtime compute speed and cross-entropy error boundary optimization.

Panel Metric Rendered Input JSON Keys Analytical Value Panel 1 Global Convergence Loss train_loss, val_loss Juxtaposes global training loss against central evaluation validation loss. Used to monitor training convergence speed and detect overfitting thresholds. Panel 2 Per-Client Loss Variance client_x_loss Overlays explicit loss trajectories of isolated edge nodes. Highlights system robustness under complex, highly non-IID data distributions. Panel 3 On-Device Token Throughput token_throughput Evaluates hardware compute efficiency measured in tokens/sec. Proves that advanced quantization layers do not degrade processing speed. Production Layout Engine & Stylesheet

The script overrides Matplotlib defaults to enforce professional typographical hierarchies and clean geometric layouts: Python

Color Palette Token Definitions

COLOR = { "haflq": "#0f62fe", # Deep Carbon Blue (Primary Target Model) "baseline": "#ff1744", # Vivid Crimson (Baseline Benchmarks) "fill": "#43a2ca", # Teal Fill (Shaded Efficiency Spaces) "grid": "#e0e0e0", # Light Grey (Axis Subdivisions) "mean": "#d73027", # Soft Red (Horizontal Reference Marks) }

Automation Subsystems

Overcrowding Decimation: Axis ticks scale dynamically using a MultipleLocator step calculation: max(1, len(rounds) // 10). This guarantees crisp, uncrowded horizontal label readouts whether running short 10-round validation sweeps or full-scale 200-round operations.

Safe Floating-Point Division: To prevent mathematical evaluation faults during early rounds where data transport counters are absolute zero, division logic is safely isolated using vector conditional logic:
Python

with np.errstate(divide="ignore", invalid="ignore"):
    efficiency = np.where(total_comm_mb > 0, global_accuracy / total_comm_mb, 0.0)

Execution Guide & Command Line Interface

The script uses an independent parser loop, allowing execution from varying workspace directories without risking file-path breaks. Command Line Arguments Plaintext

options: -h, --help show this help message and exit --input INPUT Path to accuracy_log.json source file (Default: experiments/results/accuracy_log.json) --outdir OUTDIR Directory target path for generated image files (Default: experiments/results)

Execution Recipes

1. Standard Run (Default Workspace Organization) Bash

python plot_convergence.py

2. Evaluating Custom Stored Metrics Bash

python plot_convergence.py --input storage/logs/banking77_run.json

3. Custom Output Directory Targeting (For Presentation Assets) Bash

python plot_convergence.py
--input experiments/results/accuracy_log.json
--outdir assets/presentation_deck/

Clean System Outputs

Upon validation and parsing, the engine outputs explicit generation notifications to stdout: Plaintext

Loaded log: 2 method(s), 20 rounds each. Generating Figure 1 — convergence plot... Saved: experiments/results/convergence_plot.png Generating Figure 2 — extended metrics plot... Saved: experiments/results/extended_metrics_plot.png Generating Figure 3 — loss throughput metrics plot... Saved: experiments/results/loss_throughput_metrics.png

All plots saved successfully. experiments/results/convergence_plot.png experiments/results/extended_metrics_plot.png experiments/results/loss_throughput_metrics.png