Metadata-Version: 2.4
Name: rsspolymlp
Version: 0.0.10
Summary: A framework for random structure search using polynomial MLPs
Author-email: Hayato Wakai <wakai@cms.mtl.kyoto-u.ac.jp>
Maintainer-email: Hayato Wakai <wakai@cms.mtl.kyoto-u.ac.jp>
License-Expression: MIT
Project-URL: homepage, https://github.com/hytwakai/rsspolymlp
Project-URL: repository, https://github.com/hytwakai/rsspolymlp
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: pypolymlp
Requires-Dist: symfc
Requires-Dist: spglib
Requires-Dist: joblib
Provides-Extra: pymatgen
Requires-Dist: pymatgen; extra == "pymatgen"
Provides-Extra: matplotlib
Requires-Dist: matplotlib; extra == "matplotlib"
Provides-Extra: seaborn
Requires-Dist: seaborn; extra == "seaborn"
Provides-Extra: tools
Requires-Dist: pymatgen; extra == "tools"
Requires-Dist: matplotlib; extra == "tools"
Requires-Dist: seaborn; extra == "tools"
Dynamic: license-file

# A framework for random structure search (RSS) using polynomial MLPs

## Citation of rsspolymlp

If you use `rsspolymlp` in your study, please cite the following articles.

“Efficient global crystal structure prediction using polynomial machine learning potential in the binary Al–Cu alloy system”, [J. Ceram. Soc. Jpn. 131, 762 (2023)](https://www.jstage.jst.go.jp/article/jcersj2/131/10/131_23053/_article/-char/ja/)
```
@article{HayatoWakai202323053,
  title="{Efficient global crystal structure prediction using polynomial machine learning potential in the binary Al–Cu alloy system}",
  author={Hayato Wakai and Atsuto Seko and Isao Tanaka},
  journal={J. Ceram. Soc. Jpn.},
  volume={131},
  number={10},
  pages={762-766},
  year={2023},
  doi={10.2109/jcersj2.23053}
}
```

## Installation

### Required libraries and python modules

- python >= 3.9
- pypolymlp
- symfc
- spglib
- joblib

[Optional]
- matplotlib (if plotting RSS results)
- seaborn (if plotting RSS results)

### How to install
- Install from conda-forge

| Name | Downloads | Version | Platforms |
| --- | --- | --- | --- |
| [![Conda Recipe](https://img.shields.io/badge/recipe-rsspolymlp-green.svg)](https://anaconda.org/conda-forge/rsspolymlp) | [![Conda Downloads](https://img.shields.io/conda/dn/conda-forge/rsspolymlp.svg)](https://anaconda.org/conda-forge/rsspolymlp) | [![Conda Version](https://img.shields.io/conda/vn/conda-forge/rsspolymlp.svg)](https://anaconda.org/conda-forge/rsspolymlp) | [![Conda Platforms](https://img.shields.io/conda/pn/conda-forge/rsspolymlp.svg)](https://anaconda.org/conda-forge/rsspolymlp) |

```shell
conda create -n rsspolymlp
conda activate rsspolymlp
conda install -c conda-forge rsspolymlp
```

- Install from PyPI
```shell
conda create -n rsspolymlp
conda activate rsspolymlp
conda install -c conda-forge pypolymlp symfc spglib joblib
pip install rsspolymlp
```

## Usage

### Example Commands

#### Step 1–3: Execute for each combination of pressure (`p`), composition (`c`), and number of atoms (`n`).
```shell
rss-init-struct --elements Al Cu --atom_counts 4 4 --num_init_str 2000
rss-parallel --pot polymlp.yaml --pressure 0.0 --num_opt_str 1000
rss-uniq-struct
```

#### Steps 4–6: Execute after the above steps and analyze the results aggregated by (p, c) conditions.
```shell
rss-summarize --elements Al Cu --use_joblib --rss_paths <rss_directory>/*
rss-outlier --result_paths <summary_dir>/json/*
rss-phase-analysis --elements Al Cu --result_paths <summary_dir>/json/* --thresholds 10 30 50
# <rss_directory>: parent directory of RSS runs at the same pressure
# <summary_dir>: output directory from rss-summarize, storing RSS results
```

### Workflow

<img src="docs/workflow.png" alt="single_plot" width="70%" />

The command-line interface of `rsspolymlp` is organized into 6 steps.

Steps 1–3 perform RSS using the polynomial MLP independently for each (p, c, n) conditions.

1. **Generating initial structures (`rss-init-struct`)**
   
   Random structures are generated under the specified conditions.

2. **Performing parallel geometry optimization (`rss-parallel`)**
   
   Each generated structure is optimized in parallel using polynomial MLPs.

3. **Elimination of duplicate structures (`rss-uniq-struct`)**
   
   This step processes the optimized structures. It includes:

   * Parsing optimization logs, filtering out failed or unconverged cases, and generating detailed computational summaries.
   * Removing duplicate structures and extracting unique optimized structures.
  
Steps 4–6 analyze the results aggregated over each (`p`, `c`) condition.

4. **Identifying unique structures across atom numbers (`rss-summarize`)**
   
   This step removes duplicate structures from the set of unique structures obtained at different atom counts `n` under the same pressure and composition conditions.

5. **Outlier detection (`rss-outlier`)**
   
   Identifying and filtering out anomalous structures based on energy values are performed.

6. **Phase stability analysis (`rss-phase-analysis`)**

   This step computes the relative or formation energies of structures obtained from the RSS and outputs the global minimum structures. It also identifies metastable structures near the convex hull based on a energy threshold (e.g., 30 meV/atom).

7. (Optional) Plotting RSS results (e.g., `plot-binary`)
   
   The energy distribution of structures obtained through this RSS workflow is visualized.

[Additional information is here](docs/rss.md)
