esspy 0.1.0

Unified Python interface for EwaldSolidSolution Guider and ESS

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 ([e-mail])
• Original Algorithm: Seong-Hoon Jang ([e-mail])

Requirements

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

Installation

From source

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

esspy --version
esspy --help

Quick Start

1. Initialize a project from a POSCAR file

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

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)

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

4. Export results

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

# 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

esspy run input.yaml

Development

Install in editable mode:

pip install -e ".[dev]"

Run tests:

pytest tests/ -v

Build without installing:

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