{"id":13478062,"url":"https://github.com/ORNL/HydraGNN","last_synced_at":"2025-03-27T07:30:43.307Z","repository":{"id":37492788,"uuid":"371569604","full_name":"ORNL/HydraGNN","owner":"ORNL","description":"Distributed PyTorch implementation of multi-headed graph convolutional neural networks","archived":false,"fork":false,"pushed_at":"2024-10-29T18:15:36.000Z","size":8196,"stargazers_count":65,"open_issues_count":25,"forks_count":28,"subscribers_count":10,"default_branch":"main","last_synced_at":"2024-10-29T20:23:06.536Z","etag":null,"topics":["machine-learning"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ORNL.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-05-28T03:32:03.000Z","updated_at":"2024-10-29T18:15:40.000Z","dependencies_parsed_at":"2024-03-04T16:11:40.840Z","dependency_job_id":"062f7a09-7265-4aa2-98ae-7e49bfaa52b1","html_url":"https://github.com/ORNL/HydraGNN","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ORNL%2FHydraGNN","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ORNL%2FHydraGNN/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ORNL%2FHydraGNN/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ORNL%2FHydraGNN/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ORNL","download_url":"https://codeload.github.com/ORNL/HydraGNN/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245802197,"owners_count":20674607,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["machine-learning"],"created_at":"2024-07-31T16:01:51.947Z","updated_at":"2025-03-27T07:30:43.298Z","avatar_url":"https://github.com/ORNL.png","language":"Python","funding_links":[],"categories":["Python","Representation Learning"],"sub_categories":[],"readme":"# HydraGNN\n\nDistributed PyTorch implementation of multi-headed graph convolutional neural networks\n\n\u003cimg src=\"https://github.com/ORNL/HydraGNN/assets/2488656/a6d5369b-2a70-4eee-aa39-b2cf8dedf262\" alt=\"HydraGNN_QRcode\" width=\"300\" /\u003e\n\n\n## Capabilities\n\n\u003cimg src=\"images/Hydragnn-Overview-Latest.png\" alt=\"HydraGNN Overview\" width=\"1100\" /\u003e\n\n- **Multi-headed Prediction** for graph and node-level properties  \n- **Distributed Data Parallelism** at supercomputing level\n- **Convolutional Layers** as a hyperparameter  \n- **Geometric Equivariance** in convolution and prediction  \n- **Global Attention**\n\n\n## Dependencies\n\nTo install required packages with only basic capability (`torch`,\n`torch_geometric`, and related packages)\nand to serialize+store the processed data for later sessions (`pickle5`):\n```bash\npip install -r requirements.txt\npip install -r requirements-torch.txt\npip install -r requirements-pyg.txt\n```\n\nIf you plan to modify the code, include packages for formatting (`black`) and\ntesting (`pytest`) the code:\n```bash\npip install -r requirements-dev.txt\n```\n\nDetailed dependency installation instructions are available on the\n[Wiki](https://github.com/ORNL/HydraGNN/wiki/Install)\n\n\n## Installation\n\nAfter checking out HydgraGNN, we recommend to install HydraGNN in a\ndeveloper mode so that you can use the files in your current location\nand update them if needed:\n```bash\npython -m pip install -e .\n```\n\nOr, simply type the following in the HydraGNN directory:\n```bash\nexport PYTHONPATH=$PWD:$PYTHONPATH\n```\n\nAlternatively, if you have no plane to update, you can install\nHydraGNN in your python tree as a static package:\n```bash\npython setup.py install\n```\n\n## Running the code\n\nBelow are the four main functionalities for running the code.\n1. Training a model, including continuing from a previously trained model using configuration options:\n```python\nimport hydragnn\nhydragnn.run_training(\"examples/configuration.json\")\n```\n2. Saving a model state:\n```python\nimport hydragnn\nmodel_name = model_checkpoint.pk\nhydragnn.save_model(model, optimizer, model_name, path=\"./logs/\")\n```\n3. Loading a model state:\n```python\nimport hydragnn\nmodel_name = model_checkpoint.pk\nhydragnn.load_existing_model(model, model_name, path=\"./logs/\")\n```\n4. Making predictions from a previously trained model:\n```python\nimport hydragnn\nhydragnn.run_prediction(\"examples/configuration.json\", model)\n```\nThe `run_training` and `run_predictions` functions are convenient routines that encapsulate all the steps of the training process (data generation, data pre-processing, training of HydraGNN models, and use of trained HydraGNN models for inference) on toy problems, which are included in the CI test workflows. Both `run_training` and `run_predictions` require a JSON input file for configurable options. The `save_model` and `load_model` functions store and retrieve model checkpoints for continued training and subsequent inference. Ad-hoc example scripts where data pre-processing, training, and inference are done for specific datasets are provided in the `examples` folder.\n\n### Datasets\n\nBuilt in examples are provided for testing purposes only. One source of data to\ncreate HydraGNN surrogate predictions is DFT output on the OLCF Constellation:\nhttps://doi.ccs.ornl.gov/\n\nDetailed instructions are available on the\n[Wiki](https://github.com/ORNL/HydraGNN/wiki/Datasets)\n\n### Configurable settings\n\nHydraGNN uses a JSON configuration file (examples in `examples/`):\n\nThere are many options for HydraGNN; the dataset and model type are particularly\nimportant:\n - `[\"Verbosity\"][\"level\"]`: `0`, `1`, `2`, `3`, `4` (int)\n - `[\"Dataset\"][\"name\"]`: `CuAu_32atoms`, `FePt_32atoms`, `FeSi_1024atoms` (str)\n\nAdditionally, many important arguments fall within the `[\"NeuralNetwork\"]` section:\n\n- `[\"NeuralNetwork\"]`\n  - `[\"Architecture\"]`\n    - `[\"mpnn_type\"]`  \n      Accepted types: `CGCNN`, `DimeNet`, `EGNN`, `GAT`, `GIN`, `MACE`, `MFC`, `PAINN`, `PNAEq`, `PNAPlus`, `PNA`, `SAGE`, `SchNet` (str)\n    - `[\"num_conv_layers\"]`  \n      Examples: `1`, `2`, `3`, `4` ... (int)\n    - `[\"output_heads\"]`  \n      Task types: `node`, `graph` (int)\n    - `[\"global_attn_engine\"]`\n      Accepted types: `GPS`, `None`\n    - `[\"global_attn_type\"]`\n      Accepted types: `multihead`\n    - `[\"pe_dim\"]`\n      Dimension of positional encodings (int)\n    - `[\"global_attn_heads\"]`\n      Examples: `1`, `2`, `3`, `4` ... (int)\n    - `[\"hidden_dim\"]`  \n      Dimension of node embeddings during convolution (int) - must be a multiple of \"global_attn_heads\" if \"global_attn_engine\" is not \"None\" \n            \n\n  - `[\"Variables of Interest\"]`\n    - `[\"input_node_features\"]`  \n      Indices from nodal data used as inputs (int)\n    - `[\"output_index\"]`  \n      Indices from data used as targets (int)\n    - `[\"type\"]`  \n      Either `node` or `graph` (string)\n    - `[\"output_dim\"]`  \n      Dimensions of prediction tasks (list)\n\n  - `[\"Training\"]`\n    - `[\"num_epoch\"]`  \n      Examples: `75`, `100`, `250` (int)\n    - `[\"batch_size\"]`  \n      Examples: `16`, `32`, `64` (int)\n    - `[\"Optimizer\"][\"learning_rate\"]`  \n      Examples: `2e-3`, `0.005` (float)\n    - `[\"compute_grad_energy\"]`  \n      Use the gradient of energy to predict forces (bool)\n\n\n### Citations\n\"HydraGNN: Distributed PyTorch implementation of multi-headed graph convolutional neural networks\", Copyright ID#: 81929619\nhttps://doi.org/10.11578/dc.20211019.2\n\n## Contributing\n\nWe encourage you to contribute to HydraGNN! Please check the\n[guidelines](CONTRIBUTING.md) on how to do so.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FORNL%2FHydraGNN","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FORNL%2FHydraGNN","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FORNL%2FHydraGNN/lists"}