esspy 0.1.1

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

Option A: Interactive Wizard (Recommended for new users)

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

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

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:

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

You can override these defaults at init time:

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)

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

• 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

# 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

MPI scaling benchmark:

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:

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:

# Lookup oxidation states and bounds for elements
esspy util suggest-charges Mn Ni Cr O

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

# Generate random composition for testing
esspy util random-structure --n-atoms 112 --elements Mn,Ni,Cr,O

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

License

[To be determined]

---

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