chemphase 1.0.3

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

chemphase

Phase Diagram & Chemical Potential Heatmap Generator v5.0

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

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)

# 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

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

Structure Comparison

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

Dependencies

• pymatgen — Materials analysis library
• doped — Defect calculation tools (optional, for heatmaps)
• matplotlib — 2D plotting
• plotly — Interactive ternary diagrams

API Key

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

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

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