|
1 | 1 | # Repository Structure |
2 | 2 |
|
3 | | -Source code is organized by responsibility, not experiment name. Use the narrowest module that owns the requested change. |
| 3 | +Source code is organized by responsibility, not experiment name. Use the narrowest |
| 4 | +module that owns the requested change. |
| 5 | + |
| 6 | +The root [README.md](../README.md) shows an **abbreviated** layout tree. This file |
| 7 | +is the **detailed** map: package modules, scripts, tests, configs, and which |
| 8 | +capabilities remain after Gate 6 (see [removed-materials.md](removed-materials.md)). |
4 | 9 |
|
5 | 10 | ## Change Routing |
6 | 11 |
|
@@ -55,18 +60,133 @@ graphfl_lab/ |
55 | 60 | │ │ ├── filtering.py Laplacian / graph filter on client matrices |
56 | 61 | │ │ ├── aggregation.py weighted combine and dominance hooks |
57 | 62 | │ │ ├── targets.py aggregation_target dispatch |
58 | | -│ │ └── diagnostics.py per-round graph/control metrics |
59 | | -│ └── baselines/ non-graph and proxy baselines |
| 63 | +│ │ ├── diagnostics.py per-round graph/control metrics |
| 64 | +│ │ ├── tracing.py round trace hooks |
| 65 | +│ │ ├── momentum.py server optimizer / FedAvgM interaction |
| 66 | +│ │ ├── config_context.py per-round config snapshot for filtering |
| 67 | +│ │ └── … round_*, ema, projection, artifact_rows, … |
| 68 | +│ └── baselines/ fedavgm, fedsim, graph_smooth, dominance_aware, … |
| 69 | +├── flower_app.py Flower App entry |
| 70 | +├── flower_runner.py subprocess / engine dispatch for experiments |
| 71 | +├── config_io.py JSON load; legacy key aliases |
60 | 72 | └── experiments/ |
61 | | - ├── vision/ single_run, suite, stress_grid, sweeps |
62 | | - ├── cora/ single_run, graph_ablation helpers |
| 73 | + ├── vision/ |
| 74 | + │ ├── single_run.py one vision experiment + result JSON |
| 75 | + │ ├── suite.py multi-variant suite orchestration |
| 76 | + │ ├── stress_grid.py stress-grid runner |
| 77 | + │ └── client_count_sweep.py client-count sweep runner |
| 78 | + ├── cora/ |
| 79 | + │ ├── single_run.py Cora single run |
| 80 | + │ └── graph_ablation.py graph ablation orchestration |
63 | 81 | └── suites/vision/ |
64 | | - ├── variants.py suite token grammar |
| 82 | + ├── variants.py suite token grammar entry |
| 83 | + ├── variant_core.py core variant parsing |
| 84 | + ├── variant_targets.py graph_filtered target tokens |
| 85 | + ├── variant_sources.py graph_source tokens |
| 86 | + ├── variant_families.py family grouping for reporting |
| 87 | + ├── variant_commands.py CLI flag emission per variant |
| 88 | + ├── variant_suffixes.py _graph_filter_only and legacy suffixes |
| 89 | + ├── variant_diagnostics.py diagnostic variant tokens |
| 90 | + ├── variant_legacy.py historical token spellings (read/parse) |
65 | 91 | ├── artifacts.py result/suite path discovery |
66 | 92 | ├── reporting.py summaries, dashboard, interpretation |
| 93 | + ├── summary.py suite summary row aggregation |
| 94 | + ├── features.py suite feature columns for CSV/summary |
| 95 | + ├── metadata.py suite-level metadata helpers |
67 | 96 | └── variant_helpers.py per-variant result path resolution |
68 | 97 | ``` |
69 | 98 |
|
| 99 | +## Scripts Layout |
| 100 | + |
| 101 | +```text |
| 102 | +scripts/ |
| 103 | +├── checks/ |
| 104 | +│ ├── diagnostic_suite_preflight.py suite variant sanity before long runs |
| 105 | +│ ├── result_evidence_bundle.py validate single-run result JSON bundle |
| 106 | +│ └── prior_work_proxy_parity.py prior-work proxy summary parity check |
| 107 | +├── smoke/ |
| 108 | +│ └── prior_work_proxy.py short prior-work proxy smoke workflow |
| 109 | +├── reports/ |
| 110 | +│ ├── plot_vision_convergence.py suite convergence plots (canonical) |
| 111 | +│ ├── generate_dashboard_mockup.py dashboard mockup from suite dir |
| 112 | +│ ├── generate_diagnostic_plots.py diagnostic plot helpers |
| 113 | +│ ├── graph_label_alignment_report.py label–graph alignment report |
| 114 | +│ └── spectral_decomposition_report.py spectral decomposition analysis (math) |
| 115 | +├── analysis/ |
| 116 | +│ ├── deep_dive_vision.py per-variant deep dive (canonical) |
| 117 | +│ ├── merge_vision_fedavg_ours.py merge fedavg/ours tables |
| 118 | +│ ├── deep_dive_seed.py seed-level deep dive helper |
| 119 | +│ └── aggregate_graph_ablation.py Cora graph ablation aggregation |
| 120 | +├── dev/ |
| 121 | +│ ├── run.py gate-check and dev orchestration |
| 122 | +│ ├── golden.py golden / regression helpers |
| 123 | +│ └── migrate_serialized_objects.py pickle module-path migration utility |
| 124 | +├── util/ |
| 125 | +│ └── print_round_table.py print round table from result JSON |
| 126 | +└── archive/legacy-analysis/ frozen phase-1/2/3 analysis scripts (historical) |
| 127 | +``` |
| 128 | + |
| 129 | +Removed script names (Gate 6): `plot_general_convergence.py`, `deep_dive_general.py`, |
| 130 | +`merge_general_fedavg_ours.py` — use vision-named scripts above. |
| 131 | + |
| 132 | +## Tests Layout |
| 133 | + |
| 134 | +```text |
| 135 | +tests/ |
| 136 | +├── structure/ import boundaries, facade thinness |
| 137 | +├── graph/ graph builders, sources, registry |
| 138 | +├── strategies/graphfl/ filtering, targets, rounds, diagnostics |
| 139 | +├── strategies/baselines/ baseline strategies |
| 140 | +├── lifecycle/ aggregation, counterfactuals, contracts |
| 141 | +├── designs/ GraphFLDesign presets |
| 142 | +├── diagnostics/ result schema and evidence |
| 143 | +├── experiments/vision/ suite variants, single-run helpers |
| 144 | +├── experiments/cora/ Cora experiment helpers |
| 145 | +├── experiments/suites/vision/ artifact discovery, reporting |
| 146 | +├── cli/ CLI parsing and choices |
| 147 | +├── clients/ Flower client behavior |
| 148 | +├── core/ config_io, package imports, runner |
| 149 | +├── scripts/ report script smoke tests |
| 150 | +├── dev/ gate-check entrypoint tests |
| 151 | +└── golden/ golden-file comparisons |
| 152 | +``` |
| 153 | + |
| 154 | +## Root Launchers |
| 155 | + |
| 156 | +```text |
| 157 | +run_vision_experiment.py vision single run |
| 158 | +run_vision_suite.py vision suite |
| 159 | +run_vision_client_count_sweep.py client-count sweep |
| 160 | +run_vision_stress_grid.py stress grid |
| 161 | +run_graph_ablation.py Cora graph ablation |
| 162 | +run_experiment.py unified dispatcher (track argument) |
| 163 | +``` |
| 164 | + |
| 165 | +## Capability Checklist (post-Gate-6) |
| 166 | + |
| 167 | +All rows are **present** on `main` unless marked removed. Verification: |
| 168 | +`python -m unittest discover -s tests`, `diagnostic_suite_preflight.py`. |
| 169 | + |
| 170 | +| Capability | Entry / module | Status | |
| 171 | +|---|---|---| |
| 172 | +| Vision single run | `run_vision_experiment.py` → `experiments/vision/single_run.py` | active | |
| 173 | +| Vision suite | `run_vision_suite.py` → `experiments/vision/suite.py` | active | |
| 174 | +| Stress grid | `run_vision_stress_grid.py` | active | |
| 175 | +| Client-count sweep | `run_vision_client_count_sweep.py` | active | |
| 176 | +| Cora graph ablation | `run_graph_ablation.py` | active | |
| 177 | +| Graph-FL strategy | `strategies/graphfl/strategy.py` | active | |
| 178 | +| Baselines (FedAvgM, FedSim, …) | `strategies/baselines/` | active | |
| 179 | +| Graph builders / sources | `graph/builders.py`, `graph/sources/` | active | |
| 180 | +| Aggregation targets `graph_filtered_*` | `strategies/graphfl/targets.py` | active | |
| 181 | +| Legacy target JSON alias `spectral_filtered_*` | `canonical_aggregation_target()` | read-only input | |
| 182 | +| Diagnostic suite preflight | `scripts/checks/diagnostic_suite_preflight.py` | active | |
| 183 | +| Suite reporting / artifacts | `suites/vision/reporting.py`, `artifacts.py` | active | |
| 184 | +| Convergence plots | `scripts/reports/plot_vision_convergence.py` | active | |
| 185 | +| `run_general_*` launchers | — | **removed** | |
| 186 | +| `result_general_*` / `general_suite_*` readers | — | **removed** | |
| 187 | +| `spectral_fl` import shim | — | **removed** | |
| 188 | +| Suite launch `ours_spectral_filtered_*` | — | **removed** (reporting tag pairing retained) | |
| 189 | + |
70 | 190 | ## Compatibility Facades |
71 | 191 |
|
72 | 192 | Keep these thin. Add new logic in scoped modules, then re-export only if a stable import path requires it. |
|
0 commit comments