Metadata-Version: 2.4
Name: regfgw
Version: 0.1.0
Summary: Pre-screening of interface registry via graph-based FGW distance and Bayesian optimization
Author-email: Yuxuan Tang <y.x.tang2002@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/YuxuanTang2002/RegFGW
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.23
Requires-Dist: scipy>=1.10
Requires-Dist: scikit-learn>=1.2
Requires-Dist: pymatgen>=2023.0
Requires-Dist: ase>=3.22
Requires-Dist: networkx>=3.0
Requires-Dist: pandas>=1.5
Requires-Dist: POT>=0.9
Requires-Dist: configargparse>=1.7
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Dynamic: license-file

# RegFGW

[![Tests](https://github.com/YuxuanTang2002/RegFGW/actions/workflows/tests.yaml/badge.svg)](https://github.com/YuxuanTang2002/RegFGW/actions/workflows/tests.yaml)
[![PyPI](https://img.shields.io/pypi/v/regfgw.svg)](https://pypi.org/project/regfgw/)
[![License](https://img.shields.io/github/license/YuxuanTang2002/RegFGW.svg)](https://github.com/YuxuanTang2002/RegFGW/blob/main/LICENSE)

## Overview

RegFGW is a graph-based framework for pre-screening atomic interface registries before expensive structural relaxation. 
It uses the fused Gromov–Wasserstein (FGW) distance to quantify the structural deviation of each registry from its corresponding bulk reference. 
Bayesian optimization is then used to efficiently explore the registry space. 
This enables low-cost and physically interpretable interface modeling across diverse functional materials.

## Installation

### Installation from PyPI

The recommended installation method is via PyPI.

```bash
pip install --upgrade pip
pip install regfgw
```

### Installation from source

```bash
git clone https://github.com/YuxuanTang2002/RegFGW.git
pip install ./RegFGW
```

## Usage

RegFGW provides the `regfgw_coherent` command-line interface for coherent interface construction and registry optimization. Use `--help` to view all available options.

### Interface construction

Construct coherent interface candidates from substrate and film bulk structures:

```bash
regfgw_coherent \
  --mode build \
  --substrate substrate.cif \
  --film film.cif \
```

Construction settings can be specified as needed:

```bash
regfgw_coherent \
  --mode build \
  --substrate substrate.cif \
  --film film.cif \
  --max-miller-idx 1 \
  --substrate-layers 3 \
  --film-layers 3 \
  --gap 5.0 \
  --vacuum 20.0 \
  --zsl-max-area 150.0 \
  --zsl-area-ratio 0.06 \
  --zsl-length 0.03 \
  --zsl-angle 0.02 \
```

### Registry optimization

Construct coherent interface candidates and perform FGW-guided Bayesian optimization of selected candidates:

```bash
regfgw_coherent \
  --mode optimize \
  --substrate substrate.cif \
  --film film.cif \
  --embedding embedding.json \
  --budget 3 \
```

The construction arguments above also apply in this mode. Generated interface candidates are displayed for selection before registry optimization.

### YAML configuration

Options can also be supplied through a YAML configuration file:

```bash
regfgw_coherent --config config.yaml
```

Example configuration:

```yaml
mode: optimize
substrate: substrate.cif
film: film.cif
embedding: embedding.json
max-miller-idx: 1
substrate-layers: 3
film-layers: 3
gap: 5.0
vacuum: 20.0
budget: 3
```

Command-line arguments override values specified in the configuration file.

## Reproducibility

Structures, calculated results and analysis notebooks are provided in [`examples`](examples), with supporting scripts in [`scripts`](scripts). Detailed computational settings are described in the correponding paper.

## Citation

Please cite the RegFGW software repository until the associated publication is available.

## License
This project is licensed under the [MIT License](LICENSE).
