Metadata-Version: 2.4
Name: chemphase
Version: 1.0.2
Summary: Phase diagram & chemical potential heatmap generator — binary/ternary composition diagrams, chempot diagrams, and fixed chemical potential heatmaps from Materials Project API or local VASP data
Author: ChemPhase Team
License-Expression: MIT
Project-URL: Homepage, https://github.com/icezze/chemphase
Project-URL: Repository, https://github.com/icezze/chemphase
Project-URL: Issues, https://github.com/icezze/chemphase/issues
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Chemistry
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pymatgen>=2023.0.0
Requires-Dist: matplotlib>=3.5.0
Requires-Dist: numpy>=1.21.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: plotly>=5.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Provides-Extra: export
Requires-Dist: kaleido>=0.1.0; extra == "export"
Provides-Extra: heatmap
Requires-Dist: doped>=3.2.0; extra == "heatmap"
Dynamic: license-file

# chemphase

**Phase Diagram & Chemical Potential Heatmap Generator v5.0**

[![Python](https://img.shields.io/badge/Python-3.10%2B-blue)](https://python.org)
[![License](https://img.shields.io/badge/License-MIT-green)](LICENSE)

Generate high-quality phase diagrams from Materials Project API or local VASP calculations.

## Features

- **API Mode**: Download thermodynamic data from Materials Project database
- **Local Mode**: Read local VASP calculation directories (POSCAR + vasprun.xml/OUTCAR)
- **Hybrid Mode**: Local data + API supplement
- **Binary Composition Diagrams**: ΔE vs composition with convex hull and auto label positioning
- **Ternary Composition Diagrams**: Gibbs triangle plots (Plotly interactive) with Delaunay hull triangulation
- **Chemical Potential Diagrams**: pymatgen ChemicalPotentialDiagram (binary/ternary/quaternary)
- **Fixed Chemical Potential Heatmaps**: doped CompetingPhasesAnalyzer heatmaps (requires `chemphase[heatmap]`)
- **Structure Comparison**: Detect crystal structure differences between local calculations and MP database

## Installation

```bash
pip install chemphase

# With heatmap support
pip install chemphase[heatmap]

# With PNG export support for chempot diagrams
pip install chemphase[export]
```

## Quick Start

### API Mode (default)

```bash
# Use default elements Cu-Ag-O-Se
chemphase

# Specify elements
chemphase --elements Li O Co

# With chemical potential diagrams
chemphase --elements Li O Co --chempot

# With heatmaps (requires doped)
chemphase --elements Li O Co --chempot --heatmap
```

### Local VASP Data Mode

```bash
chemphase --local /path/to/vasp/calculations --elements Cu Ag O Se
```

### Structure Comparison

```bash
chemphase --local /path/to/vasp/calculations --elements Cu Ag O Se --compare-structure
```

## Dependencies

- [pymatgen](https://pymatgen.org) — Materials analysis library
- [doped](https://github.com/SMTG-Bham/doped) — Defect calculation tools (optional, for heatmaps)
- [matplotlib](https://matplotlib.org) — 2D plotting
- [plotly](https://plotly.com) — Interactive ternary diagrams

## API Key

API mode requires a Materials Project API key. Set the environment variable:

```bash
export MATERIALS_PROJECT_API_KEY=your_key_here
```

Get a key at: https://materialsproject.org/api

## Command-Line Arguments

| Argument | Description | Default |
|----------|-------------|---------|
| `--elements` | Element list | `Cu Ag O Se` |
| `--local` | Local VASP directory | — |
| `--output` | Output directory | `phase_diagrams_output` |
| `--eah` | Energy above hull threshold | `0.05` eV/atom |
| `--compare-structure` | Enable structure comparison | `False` |
| `--chempot` | Generate chemical potential diagrams | `False` |
| `--heatmap` | Generate fixed chemical potential heatmaps | `False` |
| `--debug` | Debug mode | `False` |

## Python API Usage

```python
from chemphase import (
    PhaseDiagramConfig,
    generate_binary_composition_diagram,
    generate_ternary_composition_diagram,
    generate_chempot_phase_diagram,
    find_viable_hosts,
    generate_fixed_chempot_heatmap,
)

from pathlib import Path

# Configure
config = PhaseDiagramConfig(
    api_key="your_mp_api_key",
    eah_threshold=0.05,
    output_root="my_output",
)

# Generate diagrams programmatically — see examples/ for full usage
```

## License

MIT License — see [LICENSE](LICENSE)
