mxgap 0.3

ML models to predict terminated MXene bandgaps.

MXgap: A Machine Learning Program to predict MXene Bandgaps

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 (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, currently the tool requires 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/ 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 and Energy Environ. Mater., 2024, 7, e12774.

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 .

If installed via pip, it should handle all the dependencies, but If you encounter issues, install the exact package versions specified in requirements.txt using:

pip install -r requirements.txt

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 file and, for DOS-trained models, the PBE DOSCAR file.

options:
  -h, --help            Show this help message and exit.
  -f FILES [FILES ...], --files FILES [FILES ...]
                        Specify in order the paths to the CONTCAR and DOSCAR (if needed) 
                        files 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).
  -o OUTPUT, --output OUTPUT
                        Path of the output file. By default it will generate a 
                        mxgap.info in the CONTCAR folder.
  -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/folder/

Or using the -f option to specify both CONTCAR and DOSCAR files:

mxgap -f path/to/CONTCAR path/to/DOSCAR

Also, the program can be imported as a python module. See the Jupyter Notebook for some tutorials. Here is a quick example:

from mxgap import run_prediction

path         = "examples/La2C1Cl2/"
model        = "GBC+RFR"
prediction   =  run_prediction(path, model = model)

Tests

The program has been tested using GitHub Actions for Windows, Ubuntu and MacOS with python versions >=3.9. 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.