Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/diegonti/mxgap
MXgap is a Machine Learning tool for quickly predicting the bandgap of MXene compounds with little to no effort.
https://github.com/diegonti/mxgap
computational-chemistry machine-learning mxenes
Last synced: about 2 months ago
JSON representation
MXgap is a Machine Learning tool for quickly predicting the bandgap of MXene compounds with little to no effort.
- Host: GitHub
- URL: https://github.com/diegonti/mxgap
- Owner: diegonti
- License: mit
- Created: 2024-10-08T14:45:11.000Z (3 months ago)
- Default Branch: master
- Last Pushed: 2024-10-16T08:48:34.000Z (3 months ago)
- Last Synced: 2024-10-18T03:48:11.987Z (3 months ago)
- Topics: computational-chemistry, machine-learning, mxenes
- Language: Python
- Homepage: https://pypi.org/project/mxgap/
- Size: 53.4 MB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# MXgap: A Machine Learning Program to predict MXene Bandgaps
[](https://pypi.org/project/mxgap/)
[](https://github.com/diegonti/mxgap/actions/workflows/python_tests.yaml)
## About
`mxgap` is a computational tool designed to streamline electronic structure calculations for MXenes using hybrid functionals like PBE0. By employing Machine Learning (ML) models, mxgap predicts the PBE0 bandgap based on features extracted from a PBE calculation. Here’s a detailed overview of its functionality:
### 1. Feature Extraction:
- Automatically extracts essential features and key data from a PBE calculation output, specifically tailored for [VASP](https://www.vasp.at/) (Vienna Ab initio Simulation Package) outputs.
- It leverages the structural information from the CONTCAR file, and optionally users can choose to include the density of states (DOS) from the DOSCAR file to enhance prediction accuracy, depending on the selected ML model.
- The program is designed for periodic systems. So, for now, it expects a *p*($1\times1$) terminated MXene unit cell in the CONTCAR file for proper functionality.
### 2. ML Prediction:
- Uses trained ML models to predict bandgap values, reducing the computational cost associated with performing full PBE0 calculations.
- Several ML models have been trained and are available to use. The default (and best) one is a combination of a Classifier (GBC) that discriminates metallic or semiconductor MXenes and a Regressor (RFR, trained with semiconductor MXenes) to predict the bandgap. More info about the ML models in the [models/](mxgap/models/) folder.
### 3. Output:
- Generates a report file, `mxgap.info`, which contains the ML predictions and results.
This program is based on the data gathered in our works: [*J. Mater. Chem. A*, 2023, 11, 13754-13764](https://doi.org/10.1039/D3TA01933K) and [*Energy Environ. Mater.*, 2024, 7, e12774](https://doi.org/10.1002/eem2.12774).
## Installation
`mxgap` works for python >= 3.9, and can be installed using the Python package manager `pip`:
```
pip install mxgap
```
If you use conda/anaconda, the safest thing to do is to create a new environment and then install `mxgap`:
```
conda create -n mxgap python
conda activate mxgap
pip install mxgap
```
If you wish, you can install the latest version of `mxgap` from GitHub source with the commands below:
```
git clone https://github.com/diegonti/mxgap.git
cd mxgap
pip install .
```
## Usage
The program is mainly used through the CLI:
```
mxgap [-h] [-f CONTCAR [DOSCAR]] [-m MODEL] [PATH]
```
With the arguments and options explained below:
```
positional arguments:
path Specify the path to the directory containing the calculation output files, if empty, will select the current directory. Must contain at least the optimized CONTCAR, and the PBE DOSCAR for the PBE trained models.
options:
-h, --help show this help message and exit
-f FILES [FILES ...], --files FILES [FILES ...]
Specify in order the CONTCAR and DOSCAR (if needed) paths manually. The path positional argument has preference over this.
-m MODEL, --model MODEL
Choose the trained MXene-Learning model to use. By default, the most accurate version is selected (GBC+RFR_onlygap).
-l, --list List of all trained ML models available to choose.
```
So, for a quick example, the below command will look for the CONTCAR and DOSCAR files in the specified folder and use the default (best) ML model to predict the bandgap.
```
mxgap examples/La2C1Cl2/
```
Also, the program can be imported as a python module. See the [Jupyter Notebook](tutorials/tutorials.ipynb) for some tutorials. Here is a quick example:
```python
from mxgap import run_prediction
path = "examples/La2C1Cl2/"
model = "GBC+RFR"
prediction = run_prediction(path, model = model)
```
## Tests
You can run tests locally using `pytest` in the project folder:
```
cd mxgap
pytest
```
## Help
To get information about the program and its use, run the command:
```
mxgap -h
```
For any more doubts or questions, feel free to contact [me](mailto:[email protected]).