HeteroFL - 修士論文研究プロジェクト

本プロジェクトは、修士論文の研究において使用された Federated Learning (連合学習) のシミュレーションコードです。異種クライアント環境（Heterogeneous Clients）を想定した HeteroFL の実装をベースに、リソース制約やクライアント選択手法（cap_fair_mul, cap_fair_add 等）についての独自の研究・拡張を行っています。

---

📂 主要なファイル構成

• src/train_classifier_fed_static_final.py 本研究におけるメインの実行スクリプトです。独自の拡張（リソース制約の付与、動的サブモデルの割り当て、公平性を考慮したクライアント選択アルゴリズムなど）が実装されています。
• src/train_classifier_fed_orig.py 拡張を行う前のオリジナルの学習用スクリプトです。
• src/config.yml 全体のハイパーパラメータや制御設定（ユーザー数、学習クライアント割合、データ分割設定、制約の有無など）を定義する設定ファイルです。
• src/utils.py データセットごと（MNIST、CIFAR10、CIFAR100等）のエポック数やバッチサイズ、学習率やオプティマイザのスケジューラなどの詳細な学習設定がハードコード・制御されているファイルです。実行時間の短縮や調整を行う際はこちらを変更します。
• 設定など.txt 環境構築や実行コマンドの備忘録です。

---

🛠 環境構築とセットアップ

PowerShell上で Python 仮想環境 (HeteroFL-env) を有効化して実行します。

1. 仮想環境の有効化

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy Unrestricted
.\HeteroFL-env\Scripts\activate

※ 終了時は deactivate を実行してください。

2. 必要なライブラリのインストール

プロジェクトルートにある requirements.txt を用いて、必要なパッケージを一括でインストールできます。

pip install -r requirements.txt

Note: requirements.txt には主要なパッケージ（pandas, matplotlib, torchvision, tqdm, tensorboard など）が含まれていますが、PyTorch に関しては環境に合わせて Nightly（開発版） 等を別途インストールする必要がある場合があります。

3. 初期設定に関する注意事項

• MNISTデータセットの使用: 自動ダウンロードではエラーが発生するため、4つの生のデータファイルを .data/MNIST/raw/ に手動でダウンロード・配置してください。
• デバイス設定 (GPU/CPU): src/config.yml 内の device 項目を環境に合わせて変更してください（GPUを使わない場合は cuda から cpu に変更）。実行時の引数 --device で上書きすることも可能です。

---

🚀 実行方法

主な実験は src/train_classifier_fed_static_final.py を呼び出して行います。パラメータは src/config.yml をベースとしつつ、コマンドライン引数で動的に上書きが可能です。

基本的な実行コマンド例

python src/train_classifier_fed_static_final.py ^
  --run_dir ./runs/experiment_1 ^
  --data_name CIFAR10 ^
  --model_name resnet18 ^
  --device cuda ^
  --data_split_mode iid ^
  --model_mode a1 ^
  --resource_constraint_on False ^
  --resource_constraint a1-b2-c2-d2-e2 ^
  --resource_constraint_ratio 1.0 ^
  --client_selection_mode cap_fair_add

Tip: 実験パラメータの組み合わせが多いため、src/RunExp1.bat や src/RunExpDo1.bat などのバッチファイルに実験設定をまとめて記述し、一括で実行する方法が推奨されます。

主要な実行オプション (CLI 引数)

• --run_dir: 出力先のディレクトリ（必須）。ログやグラフ、CSV結果がこのディレクトリ配下に一元管理されます。
• --data_name: 使用するデータセット（CIFAR10, MNIST など）。
• --model_name: 使用するモデル（resnet18, conv など）。
• --data_split_mode: データの分割方法（iid または non-iid-n）。
• --resource_constraint_on: リソース制約を有効にするか（True / False）。
• --resource_constraint_ratio: 制約を適用するクライアントの割合。
• --client_selection_mode: クライアントの選択モード（random, cap_fair_mul, cap_fair_add など独自アルゴリズム）。

静的 (Static) と動的 (Dynamic) サブモデル割り当ての違い

本研究では、クライアントが保有するサブモデルの規模（リソース制約）に関して、「静的割り当て」と「動的割り当て」の2つのアプローチを比較・検証できます。

• 静的割り当て (src/RunExp1.bat 等で実行)

  • オプション --dyn_enable False を指定します。
  • 各クライアントのサブモデルサイズは学習開始時に決定され、ラウンドを通じて固定されます。

• 動的割り当て (src/RunExpDo1.bat 等で実行)

  • オプション --dyn_enable True を指定します。
  • ラウンドごとにクライアントの利用可能なリソース（サブモデルのサイズ）が変動する状況をシミュレートします。
  • 上下変動の確率は以下のパラメータで制御されます：
    • --dyn_p_down: サブモデルサイズが1段階下がる確率（例: 0.25）
    • --dyn_p_stay: サブモデルサイズが維持される確率（例: 0.50）
    • --dyn_p_up: サブモデルサイズが1段階上がる確率（例: 0.25）

---

📊 出力とログ

実験中および終了後、指定した --run_dir に以下のディレクトリとファイルが生成され、研究の評価に用いることができます。

• experiment_logs/experiment.log: 標準出力として表示される実験の進捗・パラメータなどのテキストログ。
• log_dict/log.csv: ラウンドごとの評価指標（Accuracy、Loss、通信量など）をまとめた CSV データ。
• plots/: 生成された評価グラフ群。
  • *_acc_loss_round.png: ラウンドと精度・損失の推移
  • *_acc_time.png, *_acc_bytes.png: 時間・通信量に対する精度の推移
  • *_select_bar.png 等: クライアントごとの選択回数や公平性の可視化ヒストグラム