Metadata-Version: 2.4
Name: ec-toolkit
Version: 0.1.0
Summary: Electrochemical thermodynamics toolkit for VASP workflows
License-Expression: MIT
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: ase>=3.25.0
Requires-Dist: astropy>=7.1.0
Requires-Dist: numpy>=2.3.1
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Provides-Extra: docs
Requires-Dist: sphinx; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints; extra == "docs"
Requires-Dist: sphinx-rtd-theme; extra == "docs"
Dynamic: license-file

# EC Toolkit

Electrochemical thermodynamics toolkit for VASP workflows:  
– Parse `OUTCAR` & `POSCAR`  
– Build reaction mechanisms from DFT energies, ZPE, and entropy  
– Compute ΔG profiles, overpotentials, & $G_{max}$
– Plot free‐energy diagrams

---

## Features

- **I/O parsers**
  - `OutcarParser.read_edft`, `read_zpe_tds`, `read_converged`, `auto_read`
  - `PoscarParser` backed by ASE, full support for selective dynamics
- **Data models**
  - `Compound`, `ElementaryStep`, `ReactionIntermediate`, `Mechanism`
- **Thermo analysis**
  - `compute_delta_g`, `compute_eta_td`, `compute_g_max`
- **Visualization**
  - `plot_free_energy` with optional η and $G_{max}$ annotations
- **Extensible**: CLI entry‐points, custom ZPE locators, caching, and more

---

## Installation

```bash
pip install ec_toolkit
```

---

## Quickstart

```python
from pathlib import Path
import matplotlib.pyplot as plt

from ec_toolkit.io.outcar import OutcarParser
from ec_toolkit.models.classes import Compound, ElementaryStep, ReactionIntermediate, Mechanism
from ec_toolkit.analysis.thermodynamics import compute_delta_g
from ec_toolkit.visualization.plotting import plot_free_energy

# 1) Read energies from VASP runs
workdir = Path("my_vasp_runs")
steps   = ["s1", "s2", "s3"]
edfts, zpes, tdss = OutcarParser.auto_read(
    workdir, steps, calc_tds=True
)

# 2) Wrap as Compounds
compounds = {
    name: Compound(name, {"dft": e, "zpe": z, "tds": t}, converged=True)
    for name, e, z, t in zip(steps, edfts, zpes, tdss)
}

# 3) Define stoichiometry & build ReactionIntermediate
stoich1 = { compounds["s1"]:-1, compounds["s2"]: +1 }
stoich2 = { compounds["s2"]:-1, compounds["s3"]: +1 }

ri1 = ReactionIntermediate(ElementaryStep(stoich1), label="s1→s2", is_electrochemical=True)
ri2 = ReactionIntermediate(ElementaryStep(stoich2), label="s2→s3", is_electrochemical=False)

# 4) Assemble Mechanism & compute ΔG profile
mech = Mechanism([ri1, ri2], eq_pot=1.23)
dg0  = compute_delta_g(mech.dE_array, mech.dZPE_array, mech.dTS_array, mech.el_steps, mech.eq_pot)

# 5) Plot
fig, ax = plt.subplots()
plot_free_energy(dg0, mech.el_steps, mech.labels, eq_pot=mech.eq_pot, annotate_eta=True)
plt.tight_layout()
plt.show()
```

## License

This project is released under the MIT License. See [License](./LICENSE) for details.

## Contributors

- Noel Marks
- Maksim Sokolov
