Metadata-Version: 2.5
Name: pya3eda
Version: 0.1.0
Summary: Python automation for Asymmetrically-constrained Adiabatic ALMO-EDA (A3EDA)
Project-URL: Homepage, https://github.com/sterling-group/PyA3EDA
Project-URL: Documentation, https://sterling-group.github.io/PyA3EDA/
Project-URL: Repository, https://github.com/sterling-group/PyA3EDA.git
Project-URL: Issues, https://github.com/sterling-group/PyA3EDA/issues
Author-email: Markus-G-S-Weiss <markus.guenter.weiss@rwth-aachen.de>
License-Expression: GPL-3.0-or-later
License-File: LICENSE
Keywords: ALMO-EDA,HPC,Q-Chem,automation,catalysis,computational chemistry,energy decomposition analysis,quantum chemistry
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: matplotlib>=3.7
Requires-Dist: numpy>=1.26
Requires-Dist: pandas>=2.2.3
Requires-Dist: pydantic>=2.5
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: interrogate>=1.7; extra == 'dev'
Requires-Dist: mkdocs-material>=9.5; extra == 'dev'
Requires-Dist: mkdocs>=1.6; extra == 'dev'
Requires-Dist: mkdocstrings[python]>=0.26; extra == 'dev'
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pandas-stubs>=2.2; extra == 'dev'
Requires-Dist: pre-commit>=3.5; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.15; extra == 'dev'
Requires-Dist: types-pyyaml; extra == 'dev'
Provides-Extra: docs
Requires-Dist: interrogate>=1.7; extra == 'docs'
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocs>=1.6; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.26; extra == 'docs'
Provides-Extra: test
Requires-Dist: pytest-cov>=5.0; extra == 'test'
Requires-Dist: pytest>=8.0; extra == 'test'
Description-Content-Type: text/markdown

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/sterling-group/PyA3EDA/main/docs/assets/logo-wordmark-dark.svg">
    <img src="https://raw.githubusercontent.com/sterling-group/PyA3EDA/main/docs/assets/logo-wordmark.svg" alt="PyA3EDA" width="380">
  </picture>
</p>

<p align="center"><strong>Python automation for Asymmetrically-constrained Adiabatic ALMO-EDA (A3EDA)</strong></p>

<div align="center">

[![CI](https://github.com/sterling-group/PyA3EDA/actions/workflows/ci.yml/badge.svg)](https://github.com/sterling-group/PyA3EDA/actions/workflows/ci.yml)
[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)](https://github.com/sterling-group/PyA3EDA/actions/workflows/ci.yml)
[![Docs](https://github.com/sterling-group/PyA3EDA/actions/workflows/docs.yml/badge.svg)](https://sterling-group.github.io/PyA3EDA/)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22738497.svg)](https://doi.org/10.5281/zenodo.22738497)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
[![License: GPL v3](https://img.shields.io/badge/license-GPL%20v3-blue.svg)](LICENSE)
[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)

</div>

PyA3EDA automates the full computational workflow for
**Asymmetrically-constrained Adiabatic ALMO-EDA (A3EDA)** calculations in
[Q-Chem](https://www.q-chem.com/).  A3EDA decomposes catalytic barriers
into physically meaningful contributions — frozen-density (FRZ),
polarisation (POL), and charge-transfer (CT) on the electronic-energy
surface, plus an additional confinement (NI) term on the Gibbs-energy
surface — revealing *how* a catalyst lowers (or raises) a reaction barrier.

📖 **Full documentation:** <https://sterling-group.github.io/PyA3EDA/>

> **Reference** — The A3EDA method is described in:
> M. G. S. Weiss, A. J. Sterling, *manuscript in preparation*.
> (DOI to be added upon publication.)
>
> **Software** — To cite the code itself, use the archived release:
> [10.5281/zenodo.22738497](https://doi.org/10.5281/zenodo.22738497).
> That is the *concept* DOI and always resolves to the latest release; to cite
> the exact version you ran, use the version DOI on that release's Zenodo
> record. Reference-manager metadata lives in [`CITATION.cff`](CITATION.cff).

---

## Features

| | |
|---|---|
| **A3EDA barrier decomposition** | Decomposes ΔΔG‡ into FRZ, POL, and CT on the E surface; adds a confinement (NI) term on the G surface to separate the cost of bringing fragments together from genuine interaction contributions. |
| **Non-interacting reference** | Separates the confinement cost of bringing fragments together from genuine catalyst–substrate interactions via a reconstructed non-interacting surface. |
| **Configuration-driven** | One YAML file defines theory levels, basis sets, catalysts, and species. Everything else is derived automatically. |
| **Candidate selection** | Automatically picks the lowest-energy preTS / postTS complex when multiple compositions exist. |
| **Catalyst-dimer correction** | Mark a catalyst `dimer: true` to add a `dimer` calculation alongside `cat` and a leading **DISS** dissociation bar on the ΔΔ‡ barplot — fully integrated into the normal build/run/extract. |
| **Local & SLURM execution** | Runs Q-Chem jobs on a laptop (background `bash`) or an HPC cluster (`sbatch`), auto-detected; `--max-cores` caps how many cores run at once (always on locally, opt-in on SLURM); new backends slot in behind the `ExecutionBackend` protocol. |
| **Publication-ready plots** | Energy-profile diagrams and grouped ΔΔ‡ barplots exported as SVG. |

## Workflow

```text
config.yaml
    │
    ▼
┌────────┐    ┌────────┐    ┌────────┐    ┌──────────┐
│ build  │ →  │  run   │ →  │ status │ →  │ extract  │
│ inputs │    │  jobs  │    │ check  │    │ & plot   │
└────────┘    └────────┘    └────────┘    └──────────┘
  Q-Chem        SLURM        progress      CSVs, SVGs,
  .in files     submit       report        profiles

         └──────────── pipeline ────────────┘
        one command: build → OPT → SP → extract
```

## Installation

PyA3EDA requires Python 3.11+.

**From PyPI:**

```bash
pip install pya3eda
```

**From GitHub** (latest `main`):

```bash
pip install git+https://github.com/sterling-group/PyA3EDA.git
```

**For development** — an editable install. The `[dev]` extra is the full set: it
pulls `[test]` (pytest, pytest-cov) and `[docs]` (mkdocs, mkdocstrings,
interrogate) plus the lint tools (ruff, mypy, pre-commit):

```bash
git clone https://github.com/sterling-group/PyA3EDA.git
cd PyA3EDA
pip install -e ".[dev]"
```

> **Prerequisite** — Q-Chem must be available on the target HPC cluster.
> PyA3EDA generates and parses Q-Chem files but does not bundle the
> electronic-structure code itself.

## Quick start

```bash
# 1. Generate Q-Chem input files from templates + config
pya3eda build config.yaml

# 2. Submit jobs to the cluster
pya3eda run config.yaml

# 3. Check calculation progress
pya3eda status config.yaml

# 4. Extract data, export CSVs, and generate plots
pya3eda extract config.yaml
```

> `pya3eda config.yaml` with no command is shorthand for `pya3eda status config.yaml`.

Each subcommand is incremental — you can re-run `extract` after new jobs
finish without repeating earlier steps. Or run the whole thing as one
dependency-aware pass under a core budget:

```bash
# build → submit OPTs → submit each SP as its OPT converges → extract + plot
pya3eda pipeline config.yaml --max-cores 16
```

See [`examples/diels-alder/`](examples/diels-alder/) for a complete
worked example (Lewis-acid catalysed Diels–Alder reaction with BF₃).

## Project layout

```text
src/pya3eda/
├── cli.py              # command-line entry point
├── config.py           # YAML → validated Pydantic models
├── registry.py         # enumerates all expected calculations
├── ids.py              # CalcID, ProfileID, data containers
├── builder/            # Q-Chem input file generation
├── runner/             # HPC submission backends
├── status/             # calculation progress checking
├── extractor/          # output parsing → profiles → ΔΔ‡
├── exporter/           # CSV + XYZ export
└── plotter/            # energy-profile & barplot SVGs
```

## Documentation

Full documentation (user guide, theory, API reference, developer guide)
is available at **<https://sterling-group.github.io/PyA3EDA/>**.

## License

This project is licensed under the
[GNU General Public License v3.0](LICENSE).
