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:
- 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.
- 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.
- 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.
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
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)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
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.