wfrfmodel 2.3.3

Random Forest Model to predict the work function of surfaces

Work Function Random Forest Model

The module contains the random forest ML model to predict the work function of metallic surfaces with physics-based descriptors accompanying the publication.
The ML model was trained on a work function database generated by high-throughput density functional theory, which can be found here:
Please, cite the following paper if you use the model in your research:

@article{Schindler2024,
	author = {Schindler, Peter and Antoniuk, Evan R. and Cheon, Gowoon and Zhu, Yanbing and Reed, Evan J.},
	title = {{Discovery of Stable Surfaces with Extreme Work Functions by High-Throughput Density Functional Theory and Machine Learning}},
	journal = {Adv. Funct. Mater.},
	volume = {34},
	number = {19},
	pages = {2401764},
	year = {2024},
	month = may,
	issn = {1616-301X},
	publisher = {John Wiley {\&} Sons, Ltd},
	doi = {10.1002/adfm.202401764}
}

Installation

The Python module can be installed by following these steps:

1. pip install wfrfmodel (or by using uv)
   Alternatively: Clone the repository and run pip install . in the repository base folder.
2. Run the command python -c "import wfrfmodel; wfrfmodel.download_model_file()" to download the ML model joblib file.
   Alternatively: Download file RF_1748260280.629787.joblib from and move it to the src/wfrfmodel folder (same folder as file main.py).

Usage

The model can be easily initialized and used to predict the work functions (of the top and bottom surface of the slab) as follows (assuming,
you have a slab stored in file slab.cif):

from wfrfmodel import WFRFModel
from pymatgen.core import Structure

slab = Structure.from_file('slab.cif')

WFModel = WFRFModel()
print(WFModel.predict_work_functions_from_slab(slab)) 

Or from a bulk structure stored in file bulk.cif and by specifying the Miller index:

from wfrfmodel import WFRFModel
from pymatgen.core import Structure

bulk = Structure.from_file('bulk.cif')

WFModel = WFRFModel()
print(WFModel.predict_work_functions_from_bulk_and_miller(bulk, (1, 0, 0))) 

Code Documentation

Below find a detailed documentation of all WFRFModel functions and description of variables.

Function download_model_file

def download_model_file(model_filename: str = 'RF_1748260280.629787.joblib') -> None

Download the pre-trained Random Forest model file from Zenodo.

Arguments:

• model_filename: (str) Name of the joblib file containing the pre-trained Random Forest model

Returns:

None

Class WFRFModel

Class for predicting work functions using a pre-trained Random Forest model.

__init__

def __init__() -> None

Initialize the WFRFModel class and load the pre-trained model and scaler.

Arguments:

• model_filename: (str) Name of the joblib file containing the pre-trained Random Forest model

Returns:

None

predict_work_functions_from_slab

def predict_work_functions_from_slab(slab: Structure, 
                                     tol: float = 0.4, 
                                     ignificant_digits: int = 4) -> 
                                     tuple[float, float]

Predict the work functions (of top and bottom surface) from a single slab structure.

Arguments:

• slab: (Structure) Slab structure as a pymatgen Structure object
• tol: (float) Tolerance in Angstroms to determine which atoms belong to the same layer (default 0.4 A)
• significant_digits: (int) Number of significant digits to round the predicted work function (default 4)

Returns:

(tuple[float, float]) Predicted work function of the top and bottom surfaces of the slab

predict_work_functions_from_bulk_and_miller

def predict_work_functions_from_bulk_and_miller(bulk: Structure,
                                                miller: tuple[int, int, int],
                                                tol: float = 0.4,
                                                significant_digits: int = 4) ->
                                                dict[str, float]

Predict the work functions from a bulk structure and a Miller index.

Arguments:

• bulk: (Structure) Bulk structure as a pymatgen Structure object
• miller: (tuple[int, int, int]) Miller index of slab to generate
• tol: (float) Tolerance in Angstroms to determine which atoms belong to the same layer (default 0.4 A)

Returns:

(dict[str, float]) Dictionary with keys as '<termination number (i.e., 0, 1, 2,...)>, <bottom/top>, <terminating chemical species (e.g., Cs-Hg)>' and the values are the respective predicted WFs