| Name | aviary-models JSON |
| Version |
1.2.1
JSON |
| download |
| home_page | None |
| Summary | A collection of machine learning models for materials discovery |
| upload_time | 2025-08-10 00:36:56 |
| maintainer | None |
| docs_url | None |
| author | Rhys Goodall |
| requires_python | >=3.10 |
| license | MIT License Copyright (c) Rhys Goodall Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
graph neural network
machine learning
materials discovery
materials informatics
materials science
roost
self-attention
transformer
wren
wyckoff positions
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<h1 align="center">Aviary</h1>
<h4 align="center">
[](https://github.com/comprhys/aviary/graphs/contributors)
[](https://pypi.org/project/aviary-models)
[](https://github.com/comprhys/aviary/commits)
[](https://github.com/CompRhys/aviary/actions/workflows/test.yml)
[](https://results.pre-commit.ci/latest/github/CompRhys/aviary/main)
[](https://python.org/downloads)
</h4>
The aim of `aviary` is to contain multiple models for materials discovery under a common interface, over time we hope to add more models with a particular focus on coordinate-free deep learning models.
## Installation
Users can install `aviary` from source with
```sh
pip install aviary-models
```
or for an editable source install from a local clone:
```sh
git clone https://github.com/CompRhys/aviary
pip install -e ./aviary
```
## Example Use from CLI
To test the input files generation and cleaning/canonicalization please run:
```sh
python examples/inputs/poscar_to_df.py
```
This script will load and parse a subset of raw POSCAR files from the TAATA dataset and produce the `datasets/examples/examples.csv` and `datasets/examples/examples.json` files used for the next example.
For the coordinate-free `roost` and `wren` models where the inputs are easily expressed as strings we use CSV inputs.
For the structure-based `cgcnn` model we first construct `pymatgen` structures from the raw POSCAR files then determine their dictionary serializations before saving in a JSON format.
The raw POSCAR files have been selected to ensure that the subset contains all the correct endpoints for the 5 elemental species in the `Hf-N-Ti-Zr-Zn` chemical system.
To test each of the three models provided please run:
```sh
python examples/roost-example.py --train --evaluate --data-path examples/inputs/examples.csv --targets E_f --tasks regression --losses L1 --robust --epoch 10
```
```sh
python examples/wren-example.py --train --evaluate --data-path examples/inputs/examples.csv --targets E_f --tasks regression --losses L1 --robust --epoch 10
```
```sh
python examples/wrenformer-example.py --train --evaluate --data-path examples/inputs/examples.csv --targets E_f --tasks regression --losses L1 --robust --epoch 10
```
```sh
python examples/cgcnn-example.py --train --evaluate --data-path examples/inputs/examples.json --targets E_f --tasks regression --losses L1 --robust --epoch 10
```
Please note that for speed/demonstration purposes this example runs on only ~68 materials for 10 epochs - running all these examples should take < 30 sec. These examples do not have sufficient data or training to make accurate predictions, however, the same scripts were used for all experiments conducted as part of the development and publication of these models.
Consequently understanding these examples will ensure you can deploy the models as intended for your research.
## Notebooks
We also provide some notebooks that show more a more pythonic way to interact with the codebase, these examples make use of the TAATA dataset examined in the `wren` manuscript:
| | | |
| ---------------------------------------------------------------------------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| **[Roost](https://github.com/CompRhys/aviary/blob/main/examples/notebooks/Roost.ipynb)** | [![Launch Codespace]][codespace url] | [![Open in Google Colab]](https://colab.research.google.com/github/CompRhys/aviary/blob/main/examples/notebooks/Roost.ipynb) |
| **[Wren](https://github.com/CompRhys/aviary/blob/main/examples/notebooks/Wren.ipynb)** | [![Launch Codespace]][codespace url] | [![Open in Google Colab]](https://colab.research.google.com/github/CompRhys/aviary/blob/main/examples/notebooks/Wren.ipynb) |
[Open in Google Colab]: https://colab.research.google.com/assets/colab-badge.svg
[Launch Codespace]: https://img.shields.io/badge/Launch-Codespace-darkblue?logo=github
[codespace url]: https://github.com/codespaces/new?hide_repo_select=true&ref=main&repo=411272553
## Cite This Work
If you use this code please cite the relevant work:
`roost` - Predicting materials properties without crystal structure: Deep representation learning from stoichiometry. [[Paper]](https://doi.org/10.1038/s41467-020-19964-7) [[arXiv]](https://arxiv.org/abs/1910.00617)
```bibtex
@article{goodall_2020_predicting,
title={Predicting materials properties without crystal structure: Deep representation learning from stoichiometry},
author={Goodall, Rhys EA and Lee, Alpha A},
journal={Nature Communications},
volume={11},
number={1},
pages={1--9},
year={2020},
publisher={Nature Publishing Group}
}
```
`wren` - Rapid Discovery of Stable Materials by Coordinate-free Coarse Graining. [[Paper]](https://www.science.org/doi/10.1126/sciadv.abn4117) [[arXiv]](https://arxiv.org/abs/2106.11132)
```bibtex
@article{goodall_2022_rapid,
title={Rapid discovery of stable materials by coordinate-free coarse graining},
author={Goodall, Rhys EA and Parackal, Abhijith S and Faber, Felix A and Armiento, Rickard and Lee, Alpha A},
journal={Science Advances},
volume={8},
number={30},
pages={eabn4117},
year={2022},
publisher={American Association for the Advancement of Science}
}
```
`cgcnn` - Crystal Graph Convolutional Neural Networks for an Accurate and Interpretable Prediction of Material Properties. [[Paper]](https://journals.aps.org/prl/abstract/10.1103/PhysRevLett.120.145301) [[arXiv]](https://arxiv.org/abs/1710.10324)
```bibtex
@article{xie_2018_crystal,
title={Crystal graph convolutional neural networks for an accurate and interpretable prediction of material properties},
author={Xie, Tian and Grossman, Jeffrey C},
journal={Physical review letters},
volume={120},
number={14},
pages={145301},
year={2018},
publisher={APS}
}
```
## Disclaimer
This research code is provided as-is. We have checked for potential bugs and believe that the code is being shared in a bug-free state.
Raw data
{
"_id": null,
"home_page": null,
"name": "aviary-models",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "Graph Neural Network, Machine Learning, Materials Discovery, Materials Informatics, Materials Science, Roost, Self-Attention, Transformer, Wren, Wyckoff positions",
"author": "Rhys Goodall",
"author_email": "Rhys Goodall <rhys.goodall@outlook.com>",
"download_url": "https://files.pythonhosted.org/packages/58/29/1afca908657a88f0816a42af86c375666ac17e683e3ec18720150550847f/aviary_models-1.2.1.tar.gz",
"platform": null,
"description": "<h1 align=\"center\">Aviary</h1>\n\n<h4 align=\"center\">\n\n\n[](https://github.com/comprhys/aviary/graphs/contributors)\n[](https://pypi.org/project/aviary-models)\n[](https://github.com/comprhys/aviary/commits)\n[](https://github.com/CompRhys/aviary/actions/workflows/test.yml)\n[](https://results.pre-commit.ci/latest/github/CompRhys/aviary/main)\n[](https://python.org/downloads)\n\n</h4>\n\nThe aim of `aviary` is to contain multiple models for materials discovery under a common interface, over time we hope to add more models with a particular focus on coordinate-free deep learning models.\n\n## Installation\n\nUsers can install `aviary` from source with\n\n```sh\npip install aviary-models\n```\n\nor for an editable source install from a local clone:\n\n```sh\ngit clone https://github.com/CompRhys/aviary\npip install -e ./aviary\n```\n\n## Example Use from CLI\n\nTo test the input files generation and cleaning/canonicalization please run:\n\n```sh\npython examples/inputs/poscar_to_df.py\n```\n\nThis script will load and parse a subset of raw POSCAR files from the TAATA dataset and produce the `datasets/examples/examples.csv` and `datasets/examples/examples.json` files used for the next example.\nFor the coordinate-free `roost` and `wren` models where the inputs are easily expressed as strings we use CSV inputs.\nFor the structure-based `cgcnn` model we first construct `pymatgen` structures from the raw POSCAR files then determine their dictionary serializations before saving in a JSON format.\nThe raw POSCAR files have been selected to ensure that the subset contains all the correct endpoints for the 5 elemental species in the `Hf-N-Ti-Zr-Zn` chemical system.\nTo test each of the three models provided please run:\n\n```sh\npython examples/roost-example.py --train --evaluate --data-path examples/inputs/examples.csv --targets E_f --tasks regression --losses L1 --robust --epoch 10\n```\n\n```sh\npython examples/wren-example.py --train --evaluate --data-path examples/inputs/examples.csv --targets E_f --tasks regression --losses L1 --robust --epoch 10\n```\n\n```sh\npython examples/wrenformer-example.py --train --evaluate --data-path examples/inputs/examples.csv --targets E_f --tasks regression --losses L1 --robust --epoch 10\n```\n\n```sh\npython examples/cgcnn-example.py --train --evaluate --data-path examples/inputs/examples.json --targets E_f --tasks regression --losses L1 --robust --epoch 10\n```\n\nPlease note that for speed/demonstration purposes this example runs on only ~68 materials for 10 epochs - running all these examples should take < 30 sec. These examples do not have sufficient data or training to make accurate predictions, however, the same scripts were used for all experiments conducted as part of the development and publication of these models.\nConsequently understanding these examples will ensure you can deploy the models as intended for your research.\n\n## Notebooks\n\nWe also provide some notebooks that show more a more pythonic way to interact with the codebase, these examples make use of the TAATA dataset examined in the `wren` manuscript:\n\n| | | |\n| ---------------------------------------------------------------------------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |\n| **[Roost](https://github.com/CompRhys/aviary/blob/main/examples/notebooks/Roost.ipynb)** | [![Launch Codespace]][codespace url] | [![Open in Google Colab]](https://colab.research.google.com/github/CompRhys/aviary/blob/main/examples/notebooks/Roost.ipynb) |\n| **[Wren](https://github.com/CompRhys/aviary/blob/main/examples/notebooks/Wren.ipynb)** | [![Launch Codespace]][codespace url] | [![Open in Google Colab]](https://colab.research.google.com/github/CompRhys/aviary/blob/main/examples/notebooks/Wren.ipynb) |\n\n[Open in Google Colab]: https://colab.research.google.com/assets/colab-badge.svg\n[Launch Codespace]: https://img.shields.io/badge/Launch-Codespace-darkblue?logo=github\n[codespace url]: https://github.com/codespaces/new?hide_repo_select=true&ref=main&repo=411272553\n\n## Cite This Work\n\nIf you use this code please cite the relevant work:\n\n`roost` - Predicting materials properties without crystal structure: Deep representation learning from stoichiometry. [[Paper]](https://doi.org/10.1038/s41467-020-19964-7) [[arXiv]](https://arxiv.org/abs/1910.00617)\n\n```bibtex\n@article{goodall_2020_predicting,\n title={Predicting materials properties without crystal structure: Deep representation learning from stoichiometry},\n author={Goodall, Rhys EA and Lee, Alpha A},\n journal={Nature Communications},\n volume={11},\n number={1},\n pages={1--9},\n year={2020},\n publisher={Nature Publishing Group}\n}\n```\n\n`wren` - Rapid Discovery of Stable Materials by Coordinate-free Coarse Graining. [[Paper]](https://www.science.org/doi/10.1126/sciadv.abn4117) [[arXiv]](https://arxiv.org/abs/2106.11132)\n\n```bibtex\n@article{goodall_2022_rapid,\n title={Rapid discovery of stable materials by coordinate-free coarse graining},\n author={Goodall, Rhys EA and Parackal, Abhijith S and Faber, Felix A and Armiento, Rickard and Lee, Alpha A},\n journal={Science Advances},\n volume={8},\n number={30},\n pages={eabn4117},\n year={2022},\n publisher={American Association for the Advancement of Science}\n}\n```\n\n`cgcnn` - Crystal Graph Convolutional Neural Networks for an Accurate and Interpretable Prediction of Material Properties. [[Paper]](https://journals.aps.org/prl/abstract/10.1103/PhysRevLett.120.145301) [[arXiv]](https://arxiv.org/abs/1710.10324)\n\n```bibtex\n@article{xie_2018_crystal,\n title={Crystal graph convolutional neural networks for an accurate and interpretable prediction of material properties},\n author={Xie, Tian and Grossman, Jeffrey C},\n journal={Physical review letters},\n volume={120},\n number={14},\n pages={145301},\n year={2018},\n publisher={APS}\n}\n```\n\n## Disclaimer\n\nThis research code is provided as-is. We have checked for potential bugs and believe that the code is being shared in a bug-free state.\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) Rhys Goodall Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.",
"summary": "A collection of machine learning models for materials discovery",
"version": "1.2.1",
"project_urls": {
"Repo": "https://github.com/CompRhys/aviary"
},
"split_keywords": [
"graph neural network",
" machine learning",
" materials discovery",
" materials informatics",
" materials science",
" roost",
" self-attention",
" transformer",
" wren",
" wyckoff positions"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "ca8c5cc4703dae673c10e3d95618222487ef2cb02cca1d4b50ef0c3f4d9d1a6d",
"md5": "a0c9762b201e8471c986ed70a24a8bda",
"sha256": "c744e1916c722da0cf1ef6297d2906a2df9757e0aed080d3ff964cbc4843a44a"
},
"downloads": -1,
"filename": "aviary_models-1.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a0c9762b201e8471c986ed70a24a8bda",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 284484,
"upload_time": "2025-08-10T00:36:55",
"upload_time_iso_8601": "2025-08-10T00:36:55.587025Z",
"url": "https://files.pythonhosted.org/packages/ca/8c/5cc4703dae673c10e3d95618222487ef2cb02cca1d4b50ef0c3f4d9d1a6d/aviary_models-1.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "58291afca908657a88f0816a42af86c375666ac17e683e3ec18720150550847f",
"md5": "8cff3b5c0caf7eb022afeb71b28351f9",
"sha256": "a32425a1c71c64d2755ebe6ce72c8ce59b85885e7fc9034f786cdf7a36c4440d"
},
"downloads": -1,
"filename": "aviary_models-1.2.1.tar.gz",
"has_sig": false,
"md5_digest": "8cff3b5c0caf7eb022afeb71b28351f9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 277404,
"upload_time": "2025-08-10T00:36:56",
"upload_time_iso_8601": "2025-08-10T00:36:56.930438Z",
"url": "https://files.pythonhosted.org/packages/58/29/1afca908657a88f0816a42af86c375666ac17e683e3ec18720150550847f/aviary_models-1.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-10 00:36:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "CompRhys",
"github_project": "aviary",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "aviary-models"
}
