esspy 0.1.3

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

5. Finite-temperature workflow (ft)

Typical sequence:

# (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):

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

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

# 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