Upload README.md

1ce0d1e verified 17 days ago

6.43 kB

	---
	license: mit
	tags:
	- federated-learning
	- knowledge-distillation
	- point-cloud
	- 3d-classification
	- benchmarking
	- privacy-preserving
	- medical-imaging
	dataset_info:
	features:
	- name: point_cloud
	dtype: float32
	- name: label
	dtype: int64
	splits:
	- name: train
	num_examples: unknown
	- name: validation
	num_examples: unknown
	- name: test
	num_examples: unknown
	supervised: true
	task_categories:
	- image-classification
	task_ids:
	- 3d-image-classification
	pretty_name: FLKD 3D Point Cloud Benchmark
	size_categories:
	- unknown
	source_datasets:
	- craniosynostosis
	- modelnet40
	---

	# FLKD 3D Benchmark - Output Models and Results

	This directory contains pre-trained models and comprehensive results from the Benchmarking Federated Learning and Knowledge Distillation for Point Cloud Classification benchmark (ECCV 2026).

	## Overview

	This collection includes trained PointNet++ models evaluated on the 3D point cloud datasets across two training paradigms:

	- Classical Training: Centralized, single-machine model training
	- Federated Learning + Knowledge Distillation (FLKD): Distributed federated learning with knowledge distillation objectives

	All experiments were conducted with multiple random seeds to ensure robust statistical reporting of performance metrics.

	## Directory Structure

	```
	RootDir/
	└── <dataset_name></dataset_name>/
	├── classification/
	│ └── pointnet2_cls_ssg_s{seed}/
	│ ├── checkpoints/
	│ │ ├── best_model.pth
	│ │ ├── last_model.pth
	│ │ └── resume.pth
	│ ├── config.json
	│ ├── logs/
	│ │ └── train.log
	│ └── metrics.jsonl
	│
	└── flkd/federated/classification/
	└── fl_pointnet2_cls_ssg_{algorithm}_s{seed}/
	├── checkpoints/
	│ ├── best_model.pth
	│ ├── last_model.pth
	│ └── resume.pth
	├── config.json
	├── logs/
	│ └── train.log
	└── metrics.jsonl
	```

	## File Descriptions

	### Checkpoints
	- best_model.pth: Model weights achieving the highest validation accuracy during training
	- last_model.pth: Model weights from the final training round/epoch
	- resume.pth: Complete training state (model, optimizer, RNG) for resuming interrupted training

	### Configuration
	- config.json: Hyperparameters, dataset splits, model architecture, and training settings used for this experiment

	### Logs
	- train.log: Detailed per-epoch/round training logs including loss values and validation metrics

	### Metrics
	- metrics.jsonl: Machine-readable results in JSONL format containing:
	- Per-epoch/round accuracy metrics
	- Loss values
	- Training time information
	- Other performance indicators

	## Seeds and Reproducibility

	Experiments use multiple random seeds (e.g., s7, s42, s123) to report mean ± standard deviation statistics, ensuring robust statistical conclusions. Load `best_model.pth` for production use; consult `metrics.jsonl` for full seed-wise performance breakdowns.

	## Federated Learning Algorithms

	The FLKD benchmark evaluates these 13 FL algorithms:
	- FedAvg: Classical federated averaging (also called "vanilla")
	- FedProx: Proximal term regularization for heterogeneous local objectives
	- SCAFFOLD: Control variates to reduce client drift
	- FedDyn: Biased aggregation with consensus optimization
	- FedAvgM: Momentum-based federated averaging
	- FedAdam: Server-side adaptive learning rates (Adam variant)
	- FedYogi: Server-side adaptive learning rates (Yogi variant)
	- FedAdagrad: Server-side adaptive learning rates (AdaGrad variant)
	- FedMedian: Robust aggregation via median
	- FedBN: Batch norm personalization for heterogeneous local data
	- MOON: Contrastive learning to maintain consistency
	- Ditto: Explicit client-local personalization
	- FedNova: Normalized aggregation for non-IID data


	## Model Architecture

	PointNet++ (Single-Scale Grouping / SSG):
	- Multi-layer hierarchical feature learning on point clouds
	- Set Abstraction (SA) layers with ball query and PointNet modules
	- Feature Propagation (FP) layers for upsampling
	- Designed for robust 3D shape understanding

	## Usage

	### Loading a Model

	```python
	import torch

	# Load the best model for a specific configuration
	model = torch.load('pointnet2_cls_ssg_s123/checkpoints/best_model.pth')

	# Or load with full training state (for resuming)
	checkpoint = torch.load('pointnet2_cls_ssg_s123/checkpoints/resume.pth')
	model_state = checkpoint['model_state']
	optimizer_state = checkpoint['optimizer_state']
	```

	### Accessing Results

	```python
	import json

	# Load configuration
	with open('pointnet2_cls_ssg_s123/config.json') as f:
	config = json.load(f)

	# Read metrics (each line is a JSON object)
	with open('pointnet2_cls_ssg_s123/metrics.jsonl') as f:
	for line in f:
	epoch_metrics = json.loads(line)
	print(epoch_metrics)
	```

	## Citation

	If you use these models or results, please cite the original paper:

	```bibtex
	@inproceedings{aizierjiang26benchmark,
	title={Benchmarking Federated Learning and Knowledge Distillation for Point Cloud Classification},
	author={Aizierjiang Aiersilan},
	booktitle={European Conference on Computer Vision},
	organization={Springer},
	year={2026}
	}
	```

	## License

	The models and code follow the project's original license. Please refer to the main repository for detailed license information.

	## Additional Resources

	- Project Website: https://ezharjan.github.io/FLKD3DBenchmark/
	- Main Repository: https://github.com/Ezharjan/FLKD3DBenchmark/
	- Paper: Available at the project website

	## Notes

	- All models were trained using PyTorch with CUDA acceleration
	- Mixed precision (bf16) was applied where supported; exact fp32 on high performance GPUs
	- Auto-resume checkpoints enable resuming interrupted training without loss of progress
	- Metrics are reported as mean ± std across multiple random seeds for robust statistical assessment

	---

	For questions, issues, or to contribute improvements, please visit the main repository or contact the authors through the project website.