Metadata-Version: 2.2
Name: fedgraph
Version: 0.2.4
Summary: Federated Graph Learning
Home-page: https://github.com/FedGraph/fedgraph
Author: Yuhang Yao
Author-email: yuhangya@andrew.cmu.edu
Keywords: Graph Neural Networks,Federated Learning
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=2.0.0
Requires-Dist: torch-scatter>=2.0.9
Requires-Dist: torch-sparse>=0.6.15
Requires-Dist: torch-cluster>=1.6.0
Requires-Dist: torch-spline-conv>=1.2.1
Requires-Dist: torch-geometric>=2.1.0.post1
Requires-Dist: omegaconf>=2.3.0
Requires-Dist: ray[default]>=2.6.3
Requires-Dist: PyYAML>=5.4.0
Requires-Dist: attridict
Requires-Dist: torchmetrics
Requires-Dist: setuptools
Requires-Dist: sphinx_rtd_theme
Requires-Dist: sphinxcontrib-bibtex
Requires-Dist: matplotlib
Requires-Dist: sphinx_gallery
Requires-Dist: tensorboard
Requires-Dist: dtaidistance
Requires-Dist: gdown
Requires-Dist: pandas
Requires-Dist: twine==5.0.0
Requires-Dist: scikit-learn
Requires-Dist: tenseal
Requires-Dist: huggingface_hub
Requires-Dist: ogb
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Federated Graph Learning [![PyPI Downloads](https://static.pepy.tech/badge/fedgraph)](https://pepy.tech/projects/fedgraph)

[pypi-url]: https://pypi.python.org/pypi/fedgraph

**[Documentation](https://docs.fedgraph.org)** | **[Paper](https://arxiv.org/abs/2410.06340)** | **[Slack](https://join.slack.com/t/fedgraphlibrary/shared_invite/zt-2wztvbo1v-DO81DnUD86q066mxnQuWWw)**

**FedGraph** *(Federated Graph)* is a library built on top of [PyTorch Geometric (PyG)](https://www.pyg.org/),
[Ray](https://docs.ray.io/), and [PyTorch](https://pytorch.org/) to easily train Graph Neural Networks
under federated or distributed settings.

It supports various federated training methods of graph neural networks under simulated and real federated environments and supports communication between clients and the central server for model update and information aggregation.

## Main Focus
- **Federated Node Classification with Cross-Client Edges**: Our library supports communicating information stored in other clients without affecting the privacy of users.
- **Federated Link Prediction on Dynamic Graphs**: Our library supports balancing temporal heterogeneity across clients with privacy preservation.
- **Federated Graph Classification**: Our library supports federated graph classification with non-IID graphs.




## Cross Platform Training

- We support federated training across Linux, macOS, and Windows operating systems.

## Library Highlights

Whether you are a federated learning researcher or a first-time user of federated learning toolkits, here are some reasons to try out FedGraph for federated learning on graph-structured data.

- **Easy-to-use and unified API**: All it takes is 10-20 lines of code to get started with training a federated GNN model. GNN models are PyTorch models provided by PyG and DGL. The federated training process is handled by Ray. We abstract away the complexity of federated graph training and provide a unified API for training and evaluating FedGraph models.

- **Various FedGraph methods**: Most of the state-of-the-art federated graph training methods have been implemented by library developers or authors of research papers and are ready to be applied.

- **Great flexibility**: Existing FedGraph models can easily be extended for conducting your research. Simply inherit the base class of trainers and implement your methods.

- **Large-scale real-world FedGraph Training**: We focus on the need for FedGraph applications in challenging real-world scenarios with privacy preservation, and support learning on large-scale graphs across multiple clients.

## Installation
```python
pip install fedgraph
```

## Quick Start
```python
from fedgraph.federated_methods import run_fedgraph

import attridict

config = {
    # Task, Method, and Dataset Settings
    "fedgraph_task": "NC",
    "dataset": "cora",
    "method": "FedGCN",  # Federated learning method, e.g., "FedGCN"
    "iid_beta": 10000,  # Dirichlet distribution parameter for label distribution among clients
    "distribution_type": "average",  # Distribution type among clients
    # Training Configuration
    "global_rounds": 100,
    "local_step": 3,
    "learning_rate": 0.5,
    "n_trainer": 2,
    "batch_size": -1,  # -1 indicates full batch training
    # Model Structure
    "num_layers": 2,
    "num_hops": 1,  # Number of n-hop neighbors for client communication
    # Resource and Hardware Settings
    "gpu": False,
    "num_cpus_per_trainer": 1,
    "num_gpus_per_trainer": 0,
    # Logging and Output Configuration
    "logdir": "./runs",
    # Security and Privacy
    "use_encryption": False,  # Whether to use Homomorphic Encryption for secure aggregation
    # Dataset Handling Options
    "use_huggingface": False,  # Load dataset directly from Hugging Face Hub
    "saveto_huggingface": False,  # Save partitioned dataset to Hugging Face Hub
    # Scalability and Cluster Configuration
    "use_cluster": False,  # Use Kubernetes for scalability if True
}


config = attridict(config)
run_fedgraph(config)
```

## Set Up the Ray Cluster

```bash
bash setup_cluster.sh
```

## Delete the Ray Cluster

Delete the RayCluster Custom Resource:

```bash
cd ray_cluster_configs
kubectl delete -f ray_kubernetes_cluster.yaml
kubectl delete -f ray_kubernetes_ingress.yaml
```

Confirm that the RayCluster Pods are Terminated:

```bash
kubectl get pods
# Ensure the output shows no Ray pods except kuberay-operator
```

Finally, Delete the node first and then delete EKS Cluster:

```bash
kubectl get nodes -o name | xargs kubectl delete
eksctl delete cluster --region <YOUR_AWS_REGION> --name <CLUSTER_NAME>
```

## Step to Push Data to Hugging Face Hub CLI

Use the following command to login to the Hugging Face Hub CLI tool when you set "save: True" in node classification tasks if you haven't done so already:

```bash
huggingface-cli login
```

## Cite

Please cite [our paper](https://arxiv.org/abs/2410.06340) (and the respective papers of the methods used) if you use this code in your own work:

```
@article{yao2024fedgraph,
  title={FedGraph: A Research Library and Benchmark for Federated Graph Learning},
  author={Yao, Yuhang and Li, Yuan and Fan, Xinyi and Li, Junhao and Liu, Kay and Jin, Weizhao and Ravi, Srivatsan and Yu, Philip S and Joe-Wong, Carlee},
  journal={arXiv preprint arXiv:2410.06340},
  year={2024}
}
@article{yao2023fedgcn,
  title={FedGCN: Convergence-Communication Tradeoffs in Federated Training of Graph Convolutional Networks},
  author={Yao, Yuhang and Jin, Weizhao and Ravi, Srivatsan and Joe-Wong, Carlee},
  journal={Advances in Neural Information Processing Systems (NeurIPS)},
  year={2023}
}
```

Feel free to [email us](mailto:yuhangya@andrew.cmu.edu) if you wish your work to be listed in the [external resources]().
If you notice anything unexpected, please open an [issue]() and let us know.
If you have any questions or are missing a specific feature, feel free [to discuss them with us]().
We are motivated to constantly make FedGraph even better.
