Metadata-Version: 2.4
Name: wfrfmodel
Version: 2.3.3
Summary: Random Forest Model to predict the work function of surfaces
Author-email: Peter Schindler <p.schindler@northeastern.edu>
Maintainer-email: Peter Schindler <p.schindler@northeastern.edu>
License: MIT License
        
        Copyright (c) 2024 Peter Schindler
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
Project-URL: Repository, https://github.com/d2r2group/WF-RF-Model
Keywords: machine learning,materials science,work function,random forest
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: Unix
Classifier: Operating System :: MacOS
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: joblib>=1.5.1
Requires-Dist: numpy>=2.2.6
Requires-Dist: pandas>=2.2.3
Requires-Dist: pathlib>=1.0.1
Requires-Dist: pymatgen>=2025.5.2
Requires-Dist: scikit-learn>=1.6.1
Dynamic: license-file

<div align="center">
  <img alt="WFRFModel Logo" src=logo.svg width="350"><br>
</div>

# `Work Function Random Forest Model`

[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.10449567.svg)](https://zenodo.org/doi/10.5281/zenodo.10449567)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

The module contains the random forest ML model to predict the work function of metallic surfaces 
with physics-based descriptors accompanying the publication.<br>
The ML model was trained on a work function database generated by high-throughput density 
functional theory, which can be found here: [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.10381505.svg)](https://zenodo.org/doi/10.5281/zenodo.10381505) <br>
Please, cite the following [paper](https://doi.org/10.1002/adfm.202401764) 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`)<br>
**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.<br>
**Alternatively**: Download file `RF_1748260280.629787.joblib` from [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.10449567.svg)](https://zenodo.org/doi/10.5281/zenodo.10449567) 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`):

```Python
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:

```Python
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`
```python
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__`

```python
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`

```python
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`

```python
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
