Metadata-Version: 2.2
Name: esspy
Version: 0.1.3
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

### Option A: Interactive Wizard (Recommended for new users)

```bash
esspy wizard --scenario composition --output config.yaml
```

The interactive wizard guides you through structure selection, composition design, charge neutralization, substitution rules, solve strategy, and output selection with VASP KIT-style menus.
For global composition with detected site groups, wizard defaults to automatic sitewise allocation (`allocation.mode: optimize_by_ewald`), so `esspy run input.yaml` can execute end-to-end without a separate allocation command.

Use `esspy wizard -h` for current options.

### Option B: Manual Configuration

#### 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

### 2-1. Default structure selection output

By default, generated `input.yaml` includes `output.selection` and `esspy run`
automatically exports selected structures:

- mode: `auto_top_n`
- limit: `20`
- pick: `lowest`
- interval: `left-closed`
- outdir: `selected_structures`

So after run, you get:

```text
run-output/
  selected_structures/
    selected-0001.vasp
    ...
    selected-0020.vasp
    index.tsv
```

You can override these defaults at init time:

```bash
esspy init -p POSCAR \
  --selection-mode auto_top_n \
  --selection-limit 20 \
  --selection-pick lowest \
  --selection-interval left-closed
```

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

### 5. Finite-temperature workflow (`ft`)

Typical sequence:

```bash
# (recommended) use fitted charges from esspy fc
esspy ft run input.yaml --charge-model ./samples/charge_model.json \
  --temperatures 300,600,900 --n-steps 20000 --burn-in 2000 \
  --sample-every 20 --outdir ft-output --verbose

# compact summary / inspection
esspy ft report ft-output
esspy ft inspect ft-output

# draw thermo/site/SRO plots from ft CSV outputs
esspy ft plot ft-output
```

Parallel tempering (PT) notes:

- Enable PT with `--parallel-tempering --temperatures ...`.
- MPI distributed PT is activated only when `world_size == number_of_temperatures`.
  - Example: `mpirun -np 3` with `--temperatures 300,600,900`.
- If sizes do not match, `esspy` automatically falls back to independent-chain mode and records the reason in `ft_summary.json`.

Generated artifacts (main):

```text
ft-output/
  ft_summary.json
  thermo_vs_T.csv
  site_preference_vs_T.csv
  sro_vs_T.csv                  # only when --compute-sro
  thermo.png
  site_pref.png
  sro.png                       # only when sro_vs_T.csv exists
  chains/
  representatives/
```

## Features

- **Interactive Wizard:** Step-by-step configuration with charge neutralization and validation
- **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
- **Utility Tools:** Structure templates, charge lookup, and random composition generator

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

MPI scaling benchmark:

```bash
scripts/benchmark_mpi_scaling.sh input.yaml mpi-scaling-bench
```

The script runs `np=2/4/8`, stores logs per run, and prints summary lines
including elapsed walltime, processed candidates, active/idle ranks, and
imbalance ratio.
It also writes a CSV summary at:

```text
mpi-scaling-bench/scaling_summary.csv
```

## Documentation

- **CLI Help:** `esspy --help`
- **Wizard Help:** `esspy wizard -h`
- **Utility Help:** `esspy util -h`
- **Examples:** See `examples/` directory
- **Configuration:** YAML schema reference in command help

### Utility Commands

Quick-reference utilities for structure design:

```bash
# List available structure templates (Spinel, Perovskite, Rocksalt, Fluorite)
esspy util template-list

# Suggest supercell dimensions/matrix for a target atom count
esspy util supercell POSCAR --n-target-sites 224
```

Use `esspy util -h` and each subcommand's `-h` output for detailed usage.

## License

[To be determined]

---

**Version:** 0.1.2 (Pre-release)
**Last updated:** 2026-05-11
