{"id":34036038,"url":"https://github.com/sinhvt3421/scann--material","last_synced_at":"2026-04-08T17:31:03.877Z","repository":{"id":175190213,"uuid":"271684243","full_name":"sinhvt3421/scann--material","owner":"sinhvt3421","description":"Framework for material structure exploration","archived":false,"fork":false,"pushed_at":"2024-12-19T03:04:43.000Z","size":9996,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-09-23T08:44:20.851Z","etag":null,"topics":["deeplearning","interpretable","material"],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sinhvt3421.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-06-12T01:49:36.000Z","updated_at":"2024-12-19T03:04:47.000Z","dependencies_parsed_at":"2023-09-29T08:14:36.138Z","dependency_job_id":"8d347896-ecf0-40a1-b34f-df22473c6da3","html_url":"https://github.com/sinhvt3421/scann--material","commit_stats":null,"previous_names":["sinhvt3421/scannet-material","sinhvt3421/scann-material","sinhvt3421/scann--material"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/sinhvt3421/scann--material","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sinhvt3421%2Fscann--material","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sinhvt3421%2Fscann--material/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sinhvt3421%2Fscann--material/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sinhvt3421%2Fscann--material/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sinhvt3421","download_url":"https://codeload.github.com/sinhvt3421/scann--material/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sinhvt3421%2Fscann--material/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31566682,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T14:31:17.711Z","status":"ssl_error","status_checked_at":"2026-04-08T14:31:17.202Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["deeplearning","interpretable","material"],"created_at":"2025-12-13T20:08:53.807Z","updated_at":"2026-04-08T17:31:03.857Z","avatar_url":"https://github.com/sinhvt3421.png","language":"Jupyter Notebook","readme":"[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![PyPI version](https://badge.fury.io/py/scann-model.svg)](https://badge.fury.io/py/scann-model)\n![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/sinhvt3421/scann--material)\n[![Downloads](https://pepy.tech/badge/scann-model)](https://pepy.tech/project/scann-model)\n\n\n\n# Table of Contents\n\n* [Introduction](#introduction)\n* [SCANN Framework](#scann-framework)\n* [Installation](#installation)\n* [Usage](#usage)\n* [Datasets](#datasets)\n* [References](#references)\n\n\u003ca name=\"introduction\"\u003e\u003c/a\u003e\n\n# Introduction\nThis repository is the official implementation of [Towards understanding structure–property relations in materials with interpretable deep learning](https://www.nature.com/articles/s41524-023-01163-9).\n\nPlease cite us as\n\n```\n@article{Vu2023,\ndoi = {10.1038/s41524-023-01163-9},\nissn = {2057-3960},\njournal = {npj Computational Materials},\nnumber = {1},\npages = {215},\ntitle = {{Towards understanding structure–property relations in materials with interpretable deep learning}},\nurl = {https://doi.org/10.1038/s41524-023-01163-9},\nvolume = {9},\nyear = {2023}\n}\n```\n\nWe developed a `Self-Consistent Atention-based Neural Network (SCANN)` that takes advantage of a neural network to quantitatively capture\nthe contribution of the local structure of material properties.\n\nThe model captures information on atomic sites\nand their local environments by considering self-consistent long-range interactions to enrich the structural\nrepresentations of the materials. A comparative experiment was performed on benchmark datasets QM9 and Material Project (2018.6.1) to compare the performance of the proposed model with state-of-the-art representations in terms of prediction accuracy\nfor several target properties.\n\nFurthermore,\nthe quantitative contribution of each local structure to the properties of the materials can help understand\nthe structural-property relationships of the materials.\n\n\u003ca name=\"DeepAt-framework\"\u003e\u003c/a\u003e\n\n# SCANN framework\n\nThe Self-Consistent Atention-based Neural Network (SCANN) is an implementation of deep attention mechanism for materials science.\n\nFigure 1 shows the overall schematic of the model\n\n![Model architecture](resources/model_semantic.jpg)\n\u003cdiv align='center'\u003e\u003cstrong\u003eFigure 1. Schematic of  SCANN.\u003c/strong\u003e\u003c/div\u003e\n\n\u003ca name=\"usage\"\u003e\u003c/a\u003e\n\n# Installation\n\nFirstly, create a conda environment to install the package, for example:\n```\nconda create -n test python==3.9\nsource activate test\n```\n\n### Optional GPU dependencies\n\nFor hardwares that have CUDA support, the \u003cb\u003etensorflow version with gpu options\u003c/b\u003e should be installed. Please follow the installation from https://www.tensorflow.org/install for more details.\n\nTensorflow can  also be installed from ```conda``` for simplification settings:\n```\nconda install -c conda-forge tensorflow-gpu\n```\n\n#### Method 1 (directly install from git)\nYou can install the lastes development version of SCANN from this repo and install using:\n```\ngit clone https://github.com/sinhvt3421/scann-material\ncd scann-material\npython -m pip install -e .\n```\n\n#### Method 2 (using pypi)\nSCANN can be installed via pip for the latest stable version:\n```\npip install scann-model\n```\n\n# Usage\n\nOur current implementation supports a variety of use cases for users with\ndifferent requirements and experience with deep learning. Please also visit\nthe [notebooks directory](notebooks) for Jupyter notebooks with more detailed code examples.\n\nBelow is an example of predicting the \"HOMO\" and corresponding global attention score:\n\n```python\nfrom scann.utils import load_file, prepare_input_pmt\nfrom scann.models import SCANN\nimport yaml\n\n#load config and pretrained model from folders\n\nconfig = yaml.safe_load(open('trained_model/homo/config.yaml'))\nscann = SCANN(config, pretrained='trained_model/homo/model_homo.h5', mode='infer')\n\n#load file for structure using pymatgen Structure \n\nstruct = load_file('abc.xyz') # pymatgen.core.Structure \ninputs = prepare_input_pmt(struct, d_t=4.0, w_t=0.4, angle=False)  # Distance, weights threshold\n\n# Predict the target property with the ga score for interpretation\npre_target, ga_score = scann.model.predict(inputs)\n\n```\n\n## Using pre-built models\n\nIn our work, we have already built models for the QM9 [1] and Material Project 2018 [2] datasets . The model is provided as serialized HDF5+yaml files.\n\nPlease access [Models and data](https://figshare.com/projects/SCANN_models/181339) for downloading the models and preprocessed data.\n\n\n* QM9 molecule data:\n  * HOMO: Highest occupied molecular orbital energy\n  * LUMO: Lowest unoccupied molecular orbital energy\n  * Gap: energy gap\n  * α: isotropic polarizability\n  * Cv: heat capacity at 298 K\n\nThe MAEs on the various models are given below:\n\n### Performance on QM9\n\n| Property | Units      | SCANN   | SCANN\u003csup\u003e+\u003c/sup\u003e|\n|----------|------------|-------|-------|\n| HOMO     | meV         | 41 | 32 |\n| LUMO     | meV         | 37 |31|\n| Gap      | meV         | 61 |52|\n| α        | Bohr^3     | 0.141|0.115|\n| Cv       | cal/(molK) | 0.050 |0.041|\n\n### Performance  on Material Project 2018.6.1\n\n| Property | Units      | SCANN   | SCANN\u003csup\u003e+\u003c/sup\u003e|\n|----------|------------|-------|-------|\n| Ef     | meV(atom)\u003csup\u003e-1\u003c/sup\u003e        | 29 | 28 |\n| Eg     | meV         | 260 |225|\n\n\n\u003ca name=\"dataset\"\u003e\u003c/a\u003e\n\n# Datasets\n\n## Experiments\n\nThe settings for experiments specific is placed in the folder [configs](configs)\n\nWe provide an implementation for the QM9 experiments, the fullerene-MD, the Pt/graphene-MD, Material Project 2018.6.1, and SmFe12-CD [3] experiments.\n\n# Basic usage\n## Data preprocessing\nFor training new model for each datasets, please follow the below example scripts. If the data is not avaiable, please run the code ```preprocess_data.py``` for downloading and creating suitable data formats for SCANN model. For example:\n```\n$ python preprocess_data.py qm9 processed_data --dt=4.0 --wt=0.4 --p=8\n\n-----\n\n$ python preprocess_data.py mp2018 processed_data --dt=6.0 --wt=0.4 --p=8\n\n```\nThe data for \u003cb\u003eQM9\u003c/b\u003e or \u003cb\u003eMaterial Project 2018\u003c/b\u003e will be automatically downloaded and processed into folder [propessed_data](processed_data). For all avaiable datasets and options for cutoff distance/Voronoi angle, please run ```python preprocess.py --h``` to show all details.\n\n## Model training\nAfter that, please change the config file located in folder [configs](configs) for customizing the model hyperparameters or data loading/saving path.\n```\n$ python train.py homo configs/model_qm9.yaml --use_drop=True\n```\n\nFor training dataset fullerene-MD with pretrained weights from QM9 dataset, please follow these steps. The pretrained model will be load based on the path from argument. \n```\n$ python train.py homo configs/model_fullerene.yaml --pretrained=.../qm9/homo/models/model.h5\n```\n\nFor running the evaluation from pretrained weights, please follow these steps.\n```\n$ python train.py homo ..../qm9/homo/configs.yaml --pretrained=.../qm9/homo/models/model.h5  --mode=eval \n```\n\n## Model inference\nThe code ```predict_files.py``` supports loading a ```xyz``` file and predicting the properties with the pretrained models. The information about global attention (GA) score for interpreting the structure-property relationship is also provided and saved into ```xyz``` format. Please use a visualization tool such as Ovito [4] for showing the results.\n```\n$ python predict_files.py ..../models.h5 save_path.../ experiments/molecules/Dimethyl_fumarate.xyz\n``` \n![Visualization of GA scores](resources/ovito_visual.png)\n\u003cdiv align='center'\u003e\u003cstrong\u003eFigure 2. Example of SCANN prediction for LUMO property.\u003c/strong\u003e\u003c/div\u003e\n\n\u003ca name=\"usage\"\u003e\u003c/a\u003e\n\n\u003ca name=\"references\"\u003e\u003c/a\u003e\n# References\n\n[1] Ramakrishnan, R., Dral, P., Rupp, M. et al. Quantum chemistry structures and properties of 134 kilo molecules. Sci Data 1, 140022 (2014). https://doi.org/10.1038/sdata.2014.22 \n\n[2] Xie, T. \u0026 Grossman, J. C. Crystal graph convolutional neural networks for an accurate and interpretable prediction of material properties. Phys. Rev. Lett. 120, 145301 (2018). https://doi.org/10.1021/acs.chemmater.9b01294\n\n[3] Nguyen, DN., Kino, H., Miyake, T. et al. Explainable active learning in investigating structure–stability of SmFe\u003csub\u003e12-α-β\u003c/sub\u003e X\u003csub\u003eα\u003c/sub\u003eY\u003csub\u003eβ\u003c/sub\u003e structures X, Y {Mo, Zn, Co, Cu, Ti, Al, Ga}. MRS Bulletin 48, 31–44 (2023). https://doi.org/10.1557/s43577-022-00372-9\n\n[4] A. Stukowski, Visualization and Analysis of Atomistic Simulation Data with OVITO–the Open Visualization Tool, Model. Simul. Mater. Sci. Eng. 18, 15012 (2009). https://doi.org/10.1088/0965-0393/18/1/015012","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsinhvt3421%2Fscann--material","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsinhvt3421%2Fscann--material","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsinhvt3421%2Fscann--material/lists"}