Metadata-Version: 2.2
Name: esspy
Version: 0.1.0
Summary: Unified Python interface for EwaldSolidSolution Guider and ESS
Author: OpenAI Codex
Requires-Python: >=3.10
Requires-Dist: PyYAML>=6.0
Requires-Dist: spglib>=2.0
Provides-Extra: mpi
Requires-Dist: mpi4py>=3.1; extra == "mpi"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Provides-Extra: release
Requires-Dist: build>=1.2; extra == "release"
Requires-Dist: twine>=5; extra == "release"
Requires-Dist: cibuildwheel>=2.19; extra == "release"
Description-Content-Type: text/markdown

# esspy

**Exhaustive enumeration and optimization of solid-solution crystal structures using Ewald summation.**

esspy is a Python/C++ framework that automates the generation and energy ranking of solid-solution structures. It is a modern Python interface to the EwaldSolidSolution algorithm, originally implemented in C++.

## Citation

If you use esspy in your research, please cite the original algorithm paper:

> Jang, S.-H., et al. *J. Phys. Chem. A* **2023**, 127 (48), pp 10200–10212.
> https://doi.org/10.1021/acs.jpca.3c00076

## Authors

- **Python/C++ Port & Bindings:** Soungmin Bae (soungminbae@gmail.com)
- **Original Algorithm:** Seong-Hoon Jang (jang.seonghoon.b4@tohoku.ac.jp)

## Requirements

- Python 3.9+
- CMake 3.15+
- C++17-compatible compiler (GCC, Clang, MSVC)
- Optional: MPI (for distributed execution)

## Installation

### From source

```bash
git clone https://github.com/soungmin-bae/esspy.git
cd esspy
pip install -e .
```

This will compile the C++ extension using scikit-build-core and pybind11.

### Verify installation

```bash
esspy --version
esspy --help
```

## Quick Start

### 1. Initialize a project from a POSCAR file

```bash
esspy init from-poscar POSCAR.vasp -o input.yaml
```

This generates a YAML configuration template with structure and composition settings.

### 2. Run the full workflow

```bash
esspy run input.yaml --workdir run-output
```

This performs:
- **Guider:** Supercell design and ionic recipe generation
- **Solver:** Exhaustive enumeration and energy optimization
- Outputs energy-ranked structures and summary

### 3. Guide-only mode (structure design without enumeration)

```bash
esspy run input.yaml --guide-only --workdir run-guide
```

### 4. Export results

```bash
esspy guide export-guider input.yaml
esspy solve export-spec input.yaml
```

## Features

- **Guider:** Automated supercell design with ionic recipe generation
- **Solver:** Exhaustive enumeration with Monte Carlo swapping optimization
- **Symmetry:** Automatic Wyckoff position detection (via spglib)
- **MPI:** Distributed parallel enumeration across multiple ranks
- **Progress Reporting:** Real-time enumeration progress with ETA and energy tracking
- **Output Management:** Auto-increment folder naming to prevent overwrites

## Workflow Example

```yaml
# input.yaml
structure:
  poscar: POSCAR.vasp

composition:
  target_sites:
    - {element: Mn, count: 2}
    - {element: Ni, count: 2}
    - {element: Cr, count: 2}
  n_target_sites: 6

guide:
  options:
    target_cpu_time_sec: 3.0

solve:
  swap: true
  max_swap: 2

output:
  prefix: my_structure
  workdir: run-output
```

```bash
esspy run input.yaml
```

## Development

Install in editable mode:

```bash
pip install -e ".[dev]"
```

Run tests:

```bash
pytest tests/ -v
```

Build without installing:

```bash
pip install cmake scikit-build-core pybind11
cmake -B build -S .
cmake --build build
```

## Documentation

- **CLI Help:** `esspy --help`
- **Examples:** See `examples/` directory
- **Configuration:** YAML schema reference in command help

## License

[To be determined]

---

**Version:** 0.1.0 (Pre-release)  
**Last updated:** 2026-04-30
