chemphase 0.1.0__py3-none-any.whl

chemphase/__init__.py

@@ -0,0 +1,35 @@
+"""chemphase — 相图与化学势热图生成器
+
+一键从 Materials Project API 或本地 VASP 计算结果生成：
+- 二元/三元成分相图（含 Hull 连线、标签自动避让）
+- 化学势热图
+- 结构对比报告
+"""
+
+__version__ = "0.1.0"
+
+
+def __getattr__(name):
+    """惰性导入：仅在实际使用子模块时才导入"""
+    if name == "PhaseDiagramConfig":
+        from chemphase.core import PhaseDiagramConfig
+        return PhaseDiagramConfig
+    if name == "generate_binary_composition_diagram":
+        from chemphase.diagrams import generate_binary_composition_diagram
+        return generate_binary_composition_diagram
+    if name == "generate_ternary_composition_diagram":
+        from chemphase.diagrams import generate_ternary_composition_diagram
+        return generate_ternary_composition_diagram
+    if name == "main":
+        from chemphase.cli import main
+        return main
+    raise AttributeError(f"module 'chemphase' has no attribute '{name}'")
+
+
+__all__ = [
+    "__version__",
+    "PhaseDiagramConfig",
+    "generate_binary_composition_diagram",
+    "generate_ternary_composition_diagram",
+    "main",
+]

chemphase/__main__.py

@@ -0,0 +1,9 @@
+"""chemphase 命令行入口
+
+支持 python -m chemphase 调用
+"""
+
+from chemphase.cli import main
+
+if __name__ == "__main__":
+    main()

chemphase/cli.py

@@ -0,0 +1,205 @@
+"""命令行接口 (CLI)
+
+安装后通过终端命令 `chemphase` 或 `python -m chemphase` 调用
+"""
+
+import sys
+import argparse
+from pathlib import Path
+from itertools import combinations
+
+from chemphase.core import (
+    PhaseDiagramConfig, validate_elements, ensure_api_key,
+    scan_local_phases, build_local_entries, structure_comparison_report,
+    get_entries_from_mp, get_system_name, get_all_element_combinations,
+    print_banner, DEFAULT_ELEMENTS,
+)
+from chemphase.diagrams import (
+    generate_binary_composition_diagram,
+    generate_ternary_composition_diagram,
+)
+
+
+def run_local_mode(config: PhaseDiagramConfig, elements, output_root: str):
+    """本地数据模式：读取 VASP 计算结果生成相图"""
+    print(f"\n扫描本地目录: {config.local_dir}")
+    local_phases = scan_local_phases(config.local_dir, elements, config.eah_threshold)
+    print(f"找到 {len(local_phases)} 个相关相")
+
+    if not local_phases:
+        print("没有找到有效的相数据")
+        return
+
+    # 结构对比
+    if config.compare_structure:
+        print("\n" + "=" * 60)
+        print("  结构对比分析")
+        print("=" * 60)
+        report = structure_comparison_report(local_phases, config)
+        print(f"  总共对比: {report['total_compared']}")
+        print(f"  结构匹配: {report['matching']}")
+        print(f"  结构不同: {report['different']}")
+        print(f"  MP未收录: {report['not_found_in_mp']}")
+
+        import json
+        report_file = Path(output_root) / "structure_comparison_report.json"
+        report_file.parent.mkdir(parents=True, exist_ok=True)
+        with open(report_file, 'w') as f:
+            json.dump(report, f, indent=2, sort_keys=True)
+        print(f"  报告已保存: {report_file}")
+
+    entries = build_local_entries(local_phases)
+    print(f"\n构建了 {len(entries)} 个PhaseDiagramEntry")
+
+    output_dir = Path(output_root)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    binary_combos = list(combinations(elements, 2))
+    ternary_combos = list(combinations(elements, 3))
+
+    # 二元相图
+    print("\n" + "=" * 60)
+    print("  生成二元相图")
+    print("=" * 60)
+    binary_dir = output_dir / "binary"
+    binary_dir.mkdir(parents=True, exist_ok=True)
+    for e1, e2 in binary_combos:
+        sub_entries = [e for e in entries if set(e.composition.as_dict().keys()) <= {e1, e2}]
+        if len(sub_entries) >= 2:
+            generate_binary_composition_diagram(sub_entries, (e1, e2), binary_dir, "本地数据")
+
+    # 三元相图
+    print("\n" + "=" * 60)
+    print("  生成三元相图")
+    print("=" * 60)
+    ternary_dir = output_dir / "ternary"
+    ternary_dir.mkdir(parents=True, exist_ok=True)
+    for e1, e2, e3 in ternary_combos:
+        sub_entries = [e for e in entries if set(e.composition.as_dict().keys()) <= {e1, e2, e3}]
+        if len(sub_entries) >= 3:
+            generate_ternary_composition_diagram(sub_entries, (e1, e2, e3), ternary_dir, "本地数据")
+
+    print("\n" + "=" * 60)
+    print("  本地数据模式完成")
+    print("=" * 60)
+    print(f"输出目录: {output_dir}")
+
+
+def run_api_mode(config: PhaseDiagramConfig, elements, output_root: str):
+    """API 下载模式：从 Materials Project 下载数据生成相图"""
+    print(f"\n从Materials Project下载 {get_system_name(elements)} 体系数据")
+
+    output_dir = Path(output_root)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    binary_combos = list(combinations(elements, 2))
+    ternary_combos = list(combinations(elements, 3))
+
+    # 二元相图
+    print("\n" + "=" * 60)
+    print("  生成二元相图")
+    print("=" * 60)
+    binary_dir = output_dir / "binary"
+    binary_dir.mkdir(parents=True, exist_ok=True)
+    for e1, e2 in binary_combos:
+        try:
+            entries = get_entries_from_mp(config, [e1, e2])
+            if len(entries) >= 2:
+                from pymatgen.analysis.phase_diagram import PDEntry
+                pd_entries = [PDEntry(composition=e.composition, energy=e.energy, name=e.name)
+                             for e in entries]
+                generate_binary_composition_diagram(pd_entries, (e1, e2), binary_dir, "MP数据")
+        except Exception as e:
+            print(f"    - {e1}-{e2}: {e}")
+
+    # 三元相图
+    print("\n" + "=" * 60)
+    print("  生成三元相图")
+    print("=" * 60)
+    ternary_dir = output_dir / "ternary"
+    ternary_dir.mkdir(parents=True, exist_ok=True)
+    for e1, e2, e3 in ternary_combos:
+        try:
+            entries = get_entries_from_mp(config, [e1, e2, e3])
+            if len(entries) >= 3:
+                from pymatgen.analysis.phase_diagram import PDEntry
+                pd_entries = [PDEntry(composition=e.composition, energy=e.energy, name=e.name)
+                             for e in entries]
+                generate_ternary_composition_diagram(pd_entries, (e1, e2, e3), ternary_dir, "MP数据")
+        except Exception as e:
+            print(f"    - {e1}-{e2}-{e3}: {e}")
+
+    print("\n" + "=" * 60)
+    print("  API模式完成")
+    print("=" * 60)
+    print(f"输出目录: {output_dir}")
+
+
+def main():
+    """主入口函数"""
+    parser = argparse.ArgumentParser(
+        prog="chemphase",
+        description="相图与化学势热图统一生成器 v5.0",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+使用示例:
+  # API模式 - 下载CuAgOSe数据（默认）
+  chemphase
+
+  # 指定API模式的元素
+  chemphase --elements Li O Co
+
+  # 本地模式 - 读取VASP计算结果
+  chemphase --local /path/to/calculations --elements Cu Ag O Se
+
+  # 混合模式 - 本地数据为主
+  chemphase --local /path/to/data --elements Cu Ag O Se
+
+  # 启用结构对比
+  chemphase --local /path/to/data --elements Cu Ag O Se --compare-structure
+        """
+    )
+    parser.add_argument('--local', type=str, help='本地VASP计算结果目录')
+    parser.add_argument('--elements', nargs='+', help='目标元素列表（如 Cu Ag O Se）')
+    parser.add_argument('--output', default='phase_diagrams_output', help='输出目录 (默认: phase_diagrams_output)')
+    parser.add_argument('--eah', type=float, default=0.05, help='Energy above hull 阈值 (默认: 0.05 eV/atom)')
+    parser.add_argument('--compare-structure', action='store_true', help='启用本地结构 vs MP数据库对比')
+    parser.add_argument('--debug', action='store_true', help='调试模式')
+
+    args = parser.parse_args()
+
+    print_banner()
+
+    config = PhaseDiagramConfig(
+        eah_threshold=args.eah,
+        output_root=args.output,
+        local_dir=Path(args.local) if args.local else None,
+        compare_structure=args.compare_structure,
+        debug=args.debug
+    )
+
+    if args.local:
+        if not args.elements:
+            print("错误: 本地模式需要指定 --elements")
+            sys.exit(1)
+        ok, valid, errors = validate_elements(args.elements)
+        if not ok:
+            print("错误: " + ", ".join(errors))
+            sys.exit(1)
+        run_local_mode(config, valid, args.output)
+    else:
+        ensure_api_key(config)
+        elements = args.elements if args.elements else DEFAULT_ELEMENTS
+        ok, valid, errors = validate_elements(elements)
+        if not ok:
+            print("错误: " + ", ".join(errors))
+            sys.exit(1)
+        run_api_mode(config, valid, args.output)
+
+    print("\n" + "=" * 60)
+    print("  执行完成")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()

chemphase/core.py

@@ -0,0 +1,369 @@
+"""核心模块：配置管理、VASP 数据解析、Materials Project API、结构对比"""
+
+import os
+import re
+import json
+import sys
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple, Any
+from itertools import combinations
+
+# ============================================================
+# 元素验证
+# ============================================================
+VALID_ELEMENTS = {
+    'H', 'He', 'Li', 'Be', 'B', 'C', 'N', 'O', 'F', 'Ne',
+    'Na', 'Mg', 'Al', 'Si', 'P', 'S', 'Cl', 'Ar', 'K', 'Ca',
+    'Sc', 'Ti', 'V', 'Cr', 'Mn', 'Fe', 'Co', 'Ni', 'Cu', 'Zn',
+    'Ga', 'Ge', 'As', 'Se', 'Br', 'Kr', 'Rb', 'Sr', 'Y', 'Zr',
+    'Nb', 'Mo', 'Tc', 'Ru', 'Rh', 'Pd', 'Ag', 'Cd', 'In', 'Sn',
+    'Sb', 'Te', 'I', 'Xe', 'Cs', 'Ba', 'La', 'Ce', 'Pr', 'Nd',
+    'Pm', 'Sm', 'Eu', 'Gd', 'Tb', 'Dy', 'Ho', 'Er', 'Tm', 'Yb',
+    'Lu', 'Hf', 'Ta', 'W', 'Re', 'Os', 'Ir', 'Pt', 'Au', 'Hg',
+    'Tl', 'Pb', 'Bi', 'Po', 'At', 'Rn', 'Fr', 'Ra', 'Ac', 'Th',
+    'Pa', 'U', 'Np', 'Pu', 'Am', 'Cm', 'Bk', 'Cf', 'Es', 'Fm',
+    'Md', 'No', 'Lr', 'Rf', 'Db', 'Sg', 'Bh', 'Hs', 'Mt', 'Ds',
+    'Rg', 'Cn', 'Nh', 'Fl', 'Mc', 'Lv', 'Ts', 'Og'
+}
+
+EAH_THRESHOLD = 0.05         # 能量 above hull 阈值 (eV/atom)
+OUTPUT_ROOT = "phase_diagrams_output"
+UNIFIED_PHASES_DIR = "unified_phases"
+DEFAULT_ELEMENTS = ["Cu", "Ag", "O", "Se"]
+STRUCTURE_TOLERANCE = 0.2    # 结构匹配容忍度
+
+
+def validate_elements(elements: List[str]) -> Tuple[bool, List[str], List[str]]:
+    """验证元素符号是否有效"""
+    errors = []
+    valid = []
+    for elem in elements:
+        elem = elem.strip().capitalize()
+        if elem in VALID_ELEMENTS:
+            valid.append(elem)
+        else:
+            errors.append(f"'{elem}' 不是有效元素符号")
+    return len(errors) == 0, valid, errors
+
+
+# ============================================================
+# 配置类
+# ============================================================
+class PhaseDiagramConfig:
+    """相图生成配置"""
+
+    def __init__(self, api_key: str = "", eah_threshold: float = EAH_THRESHOLD,
+                 output_root: str = OUTPUT_ROOT, unified_phases_dir: str = UNIFIED_PHASES_DIR,
+                 debug: bool = False, local_dir: Optional[Path] = None,
+                 compare_structure: bool = False):
+        self.api_key = api_key or os.environ.get("MATERIALS_PROJECT_API_KEY", "")
+        self.eah_threshold = eah_threshold
+        self.output_root = output_root
+        self.unified_phases_dir = unified_phases_dir
+        self.debug = debug
+        self.local_dir = local_dir
+        self.compare_structure = compare_structure
+
+    @property
+    def database_file(self) -> Path:
+        return Path(self.unified_phases_dir) / "phases_database.json"
+
+
+def ensure_api_key(config: PhaseDiagramConfig) -> str:
+    """确保 API 密钥可用，优先从环境变量读取"""
+    if not config.api_key:
+        print("\n" + "=" * 60)
+        print("  请设置 Materials Project API 密钥")
+        print("=" * 60)
+        print("  获取方式: https://materialsproject.org/api")
+        print("  环境变量: export MATERIALS_PROJECT_API_KEY=你的密钥")
+        print()
+        key = input("  请输入API密钥: ").strip()
+        if not key:
+            print("  未输入密钥，退出")
+            sys.exit(0)
+        config.api_key = key
+        print("  ⚠ 密钥仅本次有效，建议设置环境变量 MATERIALS_PROJECT_API_KEY")
+    return config.api_key
+
+
+# ============================================================
+# 本地 VASP 数据解析
+# ============================================================
+
+def parse_energy_from_vasprun(vasprun_path: str, debug: bool = False) -> Optional[float]:
+    """从 vasprun.xml 解析最终能量"""
+    try:
+        from pymatgen.io.vasp.outputs import Vasprun
+        vr = Vasprun(vasprun_path)
+        return vr.final_energy
+    except Exception as e:
+        if debug:
+            print(f"    vasprun.xml解析失败: {e}")
+        return None
+
+
+def parse_energy_from_outcar(outcar_path: str, debug: bool = False) -> Optional[float]:
+    """从 OUTCAR 解析最终能量"""
+    try:
+        with open(outcar_path, 'r') as f:
+            content = f.read()
+        matches = re.findall(r'energy\(sigma->0\)\s*=\s*([-\d.]+)', content)
+        if matches:
+            return float(matches[-1])
+    except Exception as e:
+        if debug:
+            print(f"    OUTCAR解析失败: {e}")
+    return None
+
+
+def parse_structure_info(poscar_path: str, debug: bool = False) -> Tuple[Optional[str], Optional[int]]:
+    """从 POSCAR 解析化学式和原子数"""
+    try:
+        from pymatgen.core import Structure
+        structure = Structure.from_file(poscar_path)
+        return structure.composition.reduced_formula, structure.num_atoms
+    except Exception as e:
+        if debug:
+            print(f"    POSCAR解析失败: {e}")
+        return None, None
+
+
+def parse_phase_directory(phase_dir: Path, eah_threshold: float = EAH_THRESHOLD) -> Optional[Dict]:
+    """解析单个 VASP 计算目录"""
+    dir_name = phase_dir.name
+    name_match = re.match(r'(.+?)_EaH_([\d.]+)(_stable)?', dir_name)
+    if not name_match:
+        return None
+
+    formula_from_name = name_match.group(1)
+    eah = float(name_match.group(2))
+    is_stable = name_match.group(3) == '_stable' or eah < eah_threshold
+
+    poscar = phase_dir / "POSCAR"
+    vasprun = phase_dir / "vasprun.xml"
+    outcar = phase_dir / "OUTCAR"
+
+    if not poscar.exists():
+        return None
+
+    formula, num_atoms = parse_structure_info(str(poscar))
+    if not formula:
+        formula = formula_from_name
+
+    energy = None
+    if vasprun.exists():
+        energy = parse_energy_from_vasprun(str(vasprun))
+    elif outcar.exists():
+        energy = parse_energy_from_outcar(str(outcar))
+
+    if energy is None:
+        return None
+
+    energy_per_atom = energy / num_atoms if num_atoms else None
+    from pymatgen.core import Composition
+    elements = list(set(Composition(formula).as_dict().keys()))
+
+    return {
+        'name': dir_name,
+        'formula': formula,
+        'energy': energy,
+        'energy_per_atom': energy_per_atom,
+        'num_atoms': num_atoms,
+        'eah': eah,
+        'is_stable': is_stable,
+        'elements': elements,
+        'path': str(phase_dir)
+    }
+
+
+def scan_local_phases(local_dir: Path, target_elements: Optional[List[str]] = None,
+                      eah_threshold: float = EAH_THRESHOLD) -> List[Dict]:
+    """扫描本地目录中的所有 VASP 计算"""
+    if not local_dir.exists():
+        print(f"目录不存在: {local_dir}")
+        return []
+
+    phases = []
+    target_set = set(target_elements) if target_elements else None
+
+    for phase_dir in local_dir.iterdir():
+        if not phase_dir.is_dir():
+            continue
+        phase_data = parse_phase_directory(phase_dir, eah_threshold)
+        if phase_data is None:
+            continue
+        if target_set:
+            phase_elements = set(phase_data['elements'])
+            if not phase_elements <= target_set:
+                continue
+        phases.append(phase_data)
+
+    return phases
+
+
+def build_local_entries(phases: List[Dict]) -> List:
+    """从本地相数据构建 pymatgen PDEntry 列表"""
+    from pymatgen.core import Structure
+    from pymatgen.analysis.phase_diagram import PDEntry
+
+    entries = []
+    for phase in phases:
+        try:
+            structure = Structure.from_file(phase['path'] + "/POSCAR")
+            entry = PDEntry(
+                composition=structure.composition,
+                energy=phase['energy'],
+                name=phase['name']
+            )
+            entries.append(entry)
+        except Exception as e:
+            print(f"    构建Entry失败 {phase['name']}: {e}")
+    return entries
+
+
+# ============================================================
+# 结构对比功能
+# ============================================================
+
+def compare_structures(local_structure, mp_structure,
+                       tolerance: float = STRUCTURE_TOLERANCE) -> Dict:
+    """比较两个晶体结构的相似度"""
+    from pymatgen.analysis.structure_matcher import StructureMatcher
+    matcher = StructureMatcher(ltol=tolerance, stol=tolerance, angle_tol=10)
+    try:
+        is_same = matcher.fit(local_structure, mp_structure)
+        return {
+            'is_same': is_same,
+            'local_formula': local_structure.composition.reduced_formula,
+            'mp_formula': mp_structure.composition.reduced_formula,
+            'local_sites': len(local_structure.sites),
+            'mp_sites': len(mp_structure.sites),
+            'local_volume': local_structure.volume,
+            'mp_volume': mp_structure.volume,
+            'volume_diff_percent': abs(local_structure.volume - mp_structure.volume) / mp_structure.volume * 100
+        }
+    except Exception as e:
+        return {
+            'is_same': False,
+            'error': str(e),
+            'local_formula': local_structure.composition.reduced_formula,
+            'mp_formula': mp_structure.composition.reduced_formula
+        }
+
+
+def structure_comparison_report(local_phases: List[Dict], config: PhaseDiagramConfig) -> Dict:
+    """生成结构对比报告"""
+    from pymatgen.ext.matproj import MPRester
+    from pymatgen.core import Structure
+
+    report = {
+        'total_compared': 0,
+        'matching': 0,
+        'different': 0,
+        'not_found_in_mp': 0,
+        'details': []
+    }
+
+    if not config.api_key:
+        print("  ! 无API密钥，跳过结构对比")
+        return report
+
+    try:
+        mpr = MPRester(api_key=config.api_key)
+    except Exception as e:
+        print(f"  ! 无法连接Materials Project: {e}")
+        return report
+
+    for phase in local_phases:
+        formula = phase['formula']
+        report['total_compared'] += 1
+
+        try:
+            mp_entries = mpr.get_entries(formula, inc_structure=True)
+            if not mp_entries:
+                report['not_found_in_mp'] += 1
+                report['details'].append({
+                    'formula': formula,
+                    'status': 'not_found_in_mp',
+                    'message': f'在MP数据库中未找到 {formula}'
+                })
+                continue
+
+            local_structure = Structure.from_file(phase['path'] + "/POSCAR")
+            mp_entry = mp_entries[0]
+            mp_structure = mp_entry.structure
+
+            comparison = compare_structures(local_structure, mp_structure)
+            comparison['formula'] = formula
+            comparison['local_path'] = phase['path']
+
+            if comparison['is_same']:
+                report['matching'] += 1
+                comparison['status'] = 'matching'
+            else:
+                report['different'] += 1
+                comparison['status'] = 'different'
+
+            report['details'].append(comparison)
+
+        except Exception as e:
+            report['not_found_in_mp'] += 1
+            report['details'].append({
+                'formula': formula,
+                'status': 'error',
+                'message': str(e)
+            })
+
+    return report
+
+
+# ============================================================
+# 工具函数
+# ============================================================
+
+def get_all_element_combinations(elements: List[str], min_size: int = 2) -> List:
+    """获取元素的所有组合（从 min_size 到全部）"""
+    result = []
+    for r in range(min_size, len(elements) + 1):
+        for combo in combinations(elements, r):
+            result.append(combo)
+    return result
+
+
+def load_database(config: PhaseDiagramConfig) -> Dict:
+    """加载本地相数据库"""
+    Path(config.unified_phases_dir).mkdir(parents=True, exist_ok=True)
+    if config.database_file.exists():
+        with open(config.database_file, 'r') as f:
+            return json.load(f)
+    return {"phases": {}, "download_history": [], "element_systems": {}}
+
+
+def save_database(config: PhaseDiagramConfig, db: Dict):
+    """保存本地相数据库"""
+    Path(config.unified_phases_dir).mkdir(parents=True, exist_ok=True)
+    with open(config.database_file, 'w') as f:
+        json.dump(db, f, indent=2, sort_keys=True)
+
+
+def get_entries_from_mp(config: PhaseDiagramConfig, elements: List[str]):
+    """从 Materials Project 下载条目"""
+    from pymatgen.ext.matproj import MPRester
+    mpr = MPRester(api_key=config.api_key)
+    return mpr.get_entries_in_chemsys(elements)
+
+
+def get_system_name(elements: List[str]) -> str:
+    """获取体系名称（排序后的元素用下划线连接）"""
+    return "_".join(sorted(elements))
+
+
+def print_banner():
+    """打印启动横幅"""
+    print("""
+╔═══════════════════════════════════════════════════════════════════════════╗
+║       相图与化学势热图统一生成器 v5.0 (chemphase)                       ║
+║    Phase Diagram & Chemical Potential Heatmap Generator                 ║
+╚═══════════════════════════════════════════════════════════════════════════╝
+""")

chemphase/diagrams.py

@@ -0,0 +1,280 @@
+"""相图生成模块：二元/三元成分相图 + Hull 连线"""
+
+import numpy as np
+import matplotlib
+matplotlib.use('Agg')
+import matplotlib.pyplot as plt
+from scipy.spatial import Delaunay
+from pathlib import Path
+from typing import List, Tuple
+
+import plotly.graph_objects as go
+from pymatgen.analysis.phase_diagram import PhaseDiagram
+
+from chemphase.plotting import (
+    coord_to_cartesian, allocate_colors, calculate_label_positions,
+)
+
+# ============================================================
+# 绘图参数
+# ============================================================
+MARKER_SIZE = 25
+MARKER_LINE_WIDTH = 2
+TITLE_FONT_SIZE = 20
+LABEL_BACKGROUND = 'rgba(255,255,255,0.9)'
+
+BINARY_FIG_WIDTH = 12
+BINARY_FIG_HEIGHT = 10
+BINARY_LABEL_FONT_SIZE = 14
+BINARY_XLABEL_FONT_SIZE = 14
+BINARY_YLABEL_FONT_SIZE = 14
+BINARY_HULL_LINE_COLOR = "gray"
+BINARY_HULL_LINE_WIDTH = 1.5
+BINARY_DPI = 150
+
+TERNARY_FIG_WIDTH = 1000
+TERNARY_FIG_HEIGHT = 900
+TERNARY_LABEL_FONT_SIZE = 14
+TERNARY_TITLE_FONT_SIZE = 20
+TERNARY_HULL_LINE_COLOR = "gray"
+TERNARY_HULL_LINE_WIDTH = 1.5
+TERNARY_SHOW_HULL = True
+TERNARY_LABEL_MARGIN = 0.12
+
+
+# ============================================================
+# 二元成分相图
+# ============================================================
+
+def generate_binary_composition_diagram(entries, elements: Tuple[str, str],
+                                       output_dir: Path, title_suffix: str = "") -> bool:
+    """生成二元成分相图（ΔE vs 成分，含 Hull 连线）
+
+    Parameters
+    ----------
+    entries : list of pymatgen PDEntry
+        热力学条目列表
+    elements : tuple of (str, str)
+        两种元素符号
+    output_dir : Path
+        输出目录
+    title_suffix : str
+        标题后缀（如 "MP数据" 或 "本地数据"）
+
+    Returns
+    -------
+    bool : 是否成功生成
+    """
+    try:
+        pd = PhaseDiagram(entries)
+        phases = []
+        base_energy = None
+
+        for entry in pd.stable_entries:
+            comp_dict = entry.composition.as_dict()
+            formula = entry.composition.reduced_formula
+            total = sum(comp_dict.values())
+            x = comp_dict.get(elements[0], 0) / total if total > 0 else 0.5
+            e_per_atom = pd.get_hull_energy(entry.composition) / entry.composition.num_atoms
+
+            if base_energy is None or e_per_atom < base_energy:
+                base_energy = e_per_atom
+
+            phases.append({
+                'formula': formula, 'x': x, 'e_per_atom': e_per_atom,
+                'comp_dict': comp_dict
+            })
+
+        for phase in phases:
+            phase['delta_e'] = phase['e_per_atom'] - base_energy
+
+        phases = allocate_colors(phases)
+        fig, ax = plt.subplots(figsize=(BINARY_FIG_WIDTH, BINARY_FIG_HEIGHT))
+
+        ax.set_xlim(-0.05, 1.05)
+        y_max = max(p['delta_e'] for p in phases) if phases else 0.5
+        y_min = min(min(p['delta_e'] for p in phases), -0.05) if phases else -0.1
+        ax.set_ylim(y_min - 0.15, y_max + 0.5)
+        ax.set_xlabel(f'Composition (x in {elements[0]}$_{{1-x}}${elements[1]}$_x$)',
+                     fontsize=BINARY_XLABEL_FONT_SIZE)
+        ax.set_ylabel('ΔE (eV/atom)', fontsize=BINARY_YLABEL_FONT_SIZE)
+        ax.spines['top'].set_visible(False)
+        ax.spines['right'].set_visible(False)
+
+        # Hull 连线（Delaunay 三角剖分）
+        if len(phases) >= 3:
+            points = np.array([[p['x'], p['delta_e']] for p in phases])
+            try:
+                tri = Delaunay(points)
+                for simplex in tri.simplices:
+                    for i in range(3):
+                        ax.plot([points[simplex[i], 0], points[simplex[(i + 1) % 3], 0]],
+                               [points[simplex[i], 1], points[simplex[(i + 1) % 3], 1]],
+                               '-', color=BINARY_HULL_LINE_COLOR, linewidth=BINARY_HULL_LINE_WIDTH)
+            except Exception:
+                pass
+
+        # 标签避让
+        occupied = []
+        sorted_phases = sorted(phases, key=lambda p: p['delta_e'])
+        for phase in sorted_phases:
+            best_y_offset = 0.05
+            for y_offset_test in np.arange(0.02, 0.25, 0.02):
+                overlaps = any(abs(ey - (phase['delta_e'] + y_offset_test)) < 0.05
+                              for (ex, ey, ef) in occupied)
+                if not overlaps:
+                    best_y_offset = y_offset_test
+                    break
+            phase['label_y_offset'] = best_y_offset
+            occupied.append((phase['x'], phase['delta_e'] + best_y_offset, phase['formula']))
+
+        for phase in phases:
+            ax.plot(phase['x'], phase['delta_e'], 'o', markersize=MARKER_SIZE / 3,
+                   color=phase['color'])
+            ax.annotate(phase['formula'],
+                        (phase['x'], phase['delta_e'] + phase['label_y_offset']),
+                        xytext=(0, 5), textcoords='offset points',
+                        fontsize=BINARY_LABEL_FONT_SIZE,
+                        color=phase['color'], fontweight='bold', ha='center',
+                        bbox=dict(boxstyle='round,pad=0.3', facecolor='white',
+                                 alpha=0.8, edgecolor=phase['color']))
+
+        system_str = f"{elements[0]}-{elements[1]}"
+        suffix = f" ({title_suffix})" if title_suffix else ""
+        ax.set_title(f'{system_str}{suffix}', fontsize=TITLE_FONT_SIZE, fontweight='bold')
+        plt.tight_layout()
+
+        filename = f"binary_{elements[0]}-{elements[1]}_phase.png"
+        filepath = output_dir / filename
+        plt.savefig(str(filepath), dpi=BINARY_DPI, bbox_inches='tight')
+        plt.close('all')
+        print(f"    + {filename}")
+        return True
+    except Exception as e:
+        print(f"    - {elements[0]}-{elements[1]}: {e}")
+        return False
+
+
+# ============================================================
+# 三元成分相图
+# ============================================================
+
+def draw_triangle_boundary(fig, elems: Tuple[str, str, str]):
+    """绘制三元相图的三角形边界"""
+    triangle_x = [0, 1, 0.5, 0]
+    triangle_y = [0, 0, np.sqrt(3) / 2, 0]
+    fig.add_trace(go.Scatter(
+        x=triangle_x, y=triangle_y, mode='lines',
+        line=dict(color='black', width=4), name='边界', hoverinfo='skip'
+    ))
+    fig.add_trace(go.Scatter(
+        x=[0, 1, 0.5], y=[-0.12, -0.12, np.sqrt(3) / 2 + 0.14],
+        mode='text', text=[f"<b>{elems[0]}</b>", f"<b>{elems[1]}</b>", f"<b>{elems[2]}</b>"],
+        textfont=dict(size=24, color='black'), name='元素标签', hoverinfo='skip'
+    ))
+
+
+def draw_hull_lines(fig, phases: List[dict]):
+    """绘制三元相图的 Hull 连线（Delaunay 三角剖分）"""
+    if not TERNARY_SHOW_HULL:
+        return
+    points = np.array([[p['x'], p['y']] for p in phases])
+    if len(points) < 3:
+        return
+    tri = Delaunay(points)
+    hull_x, hull_y = [], []
+    for simplex in tri.simplices:
+        for i in range(3):
+            hull_x.extend([points[simplex[i], 0], points[simplex[(i + 1) % 3], 0], np.nan])
+            hull_y.extend([points[simplex[i], 1], points[simplex[(i + 1) % 3], 1], np.nan])
+    fig.add_trace(go.Scatter(
+        x=hull_x, y=hull_y, mode='lines',
+        line=dict(color=TERNARY_HULL_LINE_COLOR, width=TERNARY_HULL_LINE_WIDTH),
+        name='Hull连线', hoverinfo='skip'
+    ))
+
+
+def draw_phases(fig, phases: List[dict]):
+    """在三元相图上绘制相点和标签"""
+    for phase in phases:
+        fig.add_trace(go.Scatter(
+            x=[phase['x']], y=[phase['y']], mode='markers',
+            marker=dict(size=MARKER_SIZE, color=phase['color'],
+                       line=dict(color='white', width=MARKER_LINE_WIDTH)),
+            name=phase['formula'],
+            hovertemplate=f"<b>{phase['formula']}</b><br>E = {phase['e_per_atom']:.4f} eV/atom",
+            showlegend=False
+        ))
+        fig.add_annotation(
+            x=phase['label_x'], y=phase['label_y'],
+            text=f"<b>{phase['formula']}</b>", showarrow=False,
+            font=dict(size=TERNARY_LABEL_FONT_SIZE, color=phase['color']),
+            bgcolor=LABEL_BACKGROUND, bordercolor=phase['color'],
+            borderwidth=1, borderpad=3, xref='x', yref='y'
+        )
+
+
+def generate_ternary_composition_diagram(entries, elements: Tuple[str, str, str],
+                                        output_dir: Path, title_suffix: str = "") -> bool:
+    """生成三元成分相图（Gibbs 三角图，含 Hull 连线和自动避让标签）
+
+    Parameters
+    ----------
+    entries : list of pymatgen PDEntry
+        热力学条目列表
+    elements : tuple of (str, str, str)
+        三种元素符号
+    output_dir : Path
+        输出目录
+    title_suffix : str
+        标题后缀
+
+    Returns
+    -------
+    bool : 是否成功生成
+    """
+    try:
+        pd = PhaseDiagram(entries)
+        phases = []
+
+        for entry in pd.stable_entries:
+            comp_dict = entry.composition.as_dict()
+            formula = entry.composition.reduced_formula
+            x, y = coord_to_cartesian(comp_dict, elements)
+            e_per_atom = pd.get_hull_energy(entry.composition) / entry.composition.num_atoms
+            phases.append({
+                'formula': formula, 'x': x, 'y': y, 'e_per_atom': e_per_atom,
+                'comp_dict': comp_dict
+            })
+
+        phases = allocate_colors(phases)
+        phases = calculate_label_positions(phases, TERNARY_LABEL_MARGIN)
+
+        fig = go.Figure()
+        draw_triangle_boundary(fig, elements)
+        draw_hull_lines(fig, phases)
+        draw_phases(fig, phases)
+
+        system_str = "-".join(elements)
+        suffix = f" ({title_suffix})" if title_suffix else ""
+        fig.update_layout(
+            title=dict(text=f"<b>{system_str}{suffix}</b><br><sup>{len(phases)} phases</sup>",
+                      font=dict(size=TERNARY_TITLE_FONT_SIZE), x=0.5, xanchor='center'),
+            xaxis=dict(range=[-0.2, 1.2], showgrid=False, zeroline=False, showticklabels=False),
+            yaxis=dict(range=[-0.25, 1.1], showgrid=False, zeroline=False, showticklabels=False,
+                       scaleanchor='x', scaleratio=1),
+            plot_bgcolor='white', width=TERNARY_FIG_WIDTH, height=TERNARY_FIG_HEIGHT
+        )
+
+        filename = f"ternary_{elements[0]}-{elements[1]}-{elements[2]}_phase.png"
+        filepath = output_dir / filename
+        try:
+            fig.write_image(str(filepath), scale=2)
+        except Exception:
+            fig.write_html(str(filepath).replace('.png', '.html'))
+        plt.close('all')
+        print(f"    + {filename}")
+        return True
+    except Exception as e:
+        print(f"    - {elements[0]}-{elements[1]}-{elements[2]}: {e}")
+        return False

chemphase/plotting.py

@@ -0,0 +1,94 @@
+"""绘图辅助模块：坐标变换、标签定位、颜色分配、核心绘图函数"""
+
+import numpy as np
+import matplotlib
+matplotlib.use('Agg')
+import matplotlib.pyplot as plt
+from scipy.spatial import Delaunay
+from typing import Dict, List, Tuple
+
+# ============================================================
+# 全局绘图参数
+# ============================================================
+COLOR_PALETTE = [
+    "#FF0000", "#FF8800", "#FFDD00", "#00FF00", "#00FFCC", "#00BBFF",
+    "#0066FF", "#8800FF", "#FF00AA", "#FF0044", "#AAFF00", "#00FF88",
+    "#00DDFF", "#4400FF", "#DD00FF", "#4400FF", "#FF3333", "#FF9933",
+    "#FFEE33", "#33FF33", "#33FFCC", "#33CCFF", "#3388FF", "#9933FF",
+    "#FF33AA", "#FF3388", "#99FF33", "#33FF99", "#33EEFF", "#5533FF",
+    "#EE33FF", "#FF5533", "#FF6666", "#FFAA66", "#FFFF66", "#66FF66",
+    "#66FFCC", "#66DDFF", "#66AAFF", "#AA66FF", "#FF66CC", "#AAFF66",
+    "#66FFAA", "#66EEFF", "#6644FF", "#FF66FF", "#FF6644", "#FFAAAA",
+    "#FFCCAA", "#FFFFAA", "#AAFFAA", "#AAFFCC", "#AAEEFF", "#AACCFF",
+    "#CCAAFF", "#FFAAEE", "#CCFFAA", "#CC0000", "#CC6600", "#CCCC00",
+    "#00CC00", "#00CCCC", "#0099CC", "#0033CC", "#6600CC", "#CC0099",
+    "#CC0033", "#99CC00", "#00CC66",
+]
+
+# ============================================================
+# 三元相图坐标变换
+# ============================================================
+
+def coord_to_cartesian(comp_dict: Dict, elems: Tuple[str, str, str]) -> Tuple[float, float]:
+    """将三元成分坐标转换为笛卡尔坐标（等边三角形底边朝下）"""
+    total = sum(comp_dict.values())
+    if total == 0:
+        return 0.5, 0.5
+    fracs = {e: comp_dict.get(e, 0) / total for e in elems}
+    # elems[0] 在左下角, elems[1] 在右下角, elems[2] 在顶部
+    x = fracs.get(elems[1], 0) + 0.5 * fracs.get(elems[2], 0)
+    y = (np.sqrt(3) / 2) * fracs.get(elems[2], 0)
+    return x, y
+
+
+# ============================================================
+# 标签自动避让算法
+# ============================================================
+
+def find_best_label_position(px: float, py: float, occupied: List[Tuple[float, float, str]],
+                              margin: float = 0.12) -> Tuple[str, float, float]:
+    """在三元相图中为标签找到最佳位置（避免与其他标签重叠）"""
+    positions = [
+        ('top left', -0.12, 0.10), ('top right', 0.12, 0.10),
+        ('bottom left', -0.12, -0.08), ('bottom right', 0.12, -0.08),
+        ('middle left', -0.15, 0), ('middle right', 0.15, 0),
+        ('top center', 0, 0.12), ('bottom center', 0, -0.10),
+    ]
+    best_pos, best_x, best_y = 'top left', px - 0.12, py + 0.10
+    best_dist = -1
+    for pos_name, ox, oy in positions:
+        test_x, test_y = px + ox, py + oy
+        if test_y < -0.05 or test_y > 0.95:
+            continue
+        if test_x < -0.05 or test_x > 1.05:
+            continue
+        min_dist = min(((test_x - pox) ** 2 + (test_y - poy) ** 2) ** 0.5
+                       for (pox, poy, _) in occupied) if occupied else 999
+        if min_dist > best_dist:
+            best_dist = min_dist
+            best_pos, best_x, best_y = pos_name, test_x, test_y
+    return best_pos, best_x, best_y
+
+
+def calculate_label_positions(phases: List[Dict], margin: float = 0.12) -> List[Dict]:
+    """为所有相计算最佳标签位置"""
+    occupied = []
+    sorted_phases = sorted(phases, key=lambda p: p['y'])
+    for phase in sorted_phases:
+        pos, lx, ly = find_best_label_position(phase['x'], phase['y'], occupied, margin)
+        phase['label_pos'] = pos
+        phase['label_x'] = lx
+        phase['label_y'] = ly
+        occupied.append((lx, ly, phase['formula']))
+    return phases
+
+
+# ============================================================
+# 颜色分配
+# ============================================================
+
+def allocate_colors(phases: List[Dict]) -> List[Dict]:
+    """为每个相分配颜色（循环使用调色板）"""
+    for i, phase in enumerate(phases):
+        phase['color'] = COLOR_PALETTE[i % len(COLOR_PALETTE)]
+    return phases

chemphase-0.1.0.dist-info/METADATA

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: chemphase
+Version: 0.1.0
+Summary: 相图与化学势热图统一生成器 — 一键生成二元/三元成分相图、化学势热图，支持 Materials Project API 和本地 VASP 数据
+Author: Phase Diagram Generator Team
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/user/chemphase
+Project-URL: Repository, https://github.com/user/chemphase
+Project-URL: Issues, https://github.com/user/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: 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: doped>=3.2.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"
+Dynamic: license-file
+
+# chemphase
+
+**相图与化学势热图统一生成器 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)
+
+一键从 Materials Project API 或本地 VASP 计算结果生成高质量相图。
+
+## 功能
+
+- **API 模式**：从 Materials Project 数据库下载热力学数据
+- **本地模式**：读取本地 VASP 计算目录 (POSCAR + vasprun.xml/OUTCAR)
+- **混合模式**：本地数据 + API 补充
+- **二元成分相图**：ΔE vs 成分，含 Hull 连线、自动标签避让
+- **三元成分相图**：Gibbs 三角图 (Plotly 交互式)，含 Hull 三角剖分
+- **结构对比**：检测本地计算与 MP 数据库的晶体结构差异
+
+## 安装
+
+```bash
+pip install chemphase
+```
+
+## 快速开始
+
+### API 模式（默认）
+
+```bash
+# 使用默认元素 Cu-Ag-O-Se
+chemphase
+
+# 指定元素
+chemphase --elements Li O Co
+```
+
+### 本地 VASP 数据模式
+
+```bash
+chemphase --local /path/to/vasp/calculations --elements Cu Ag O Se
+```
+
+### 结构对比
+
+```bash
+chemphase --local /path/to/vasp/calculations --elements Cu Ag O Se --compare-structure
+```
+
+## 依赖
+
+- [pymatgen](https://pymatgen.org) — 材料分析库
+- [doped](https://github.com/SMTG-Bham/doped) — 缺陷计算工具
+- [matplotlib](https://matplotlib.org) — 二维绘图
+- [plotly](https://plotly.com) — 交互式三元图
+
+## API 密钥
+
+API 模式需要 Materials Project API 密钥。设置环境变量：
+
+```bash
+export MATERIALS_PROJECT_API_KEY=你的密钥
+```
+
+获取密钥：https://materialsproject.org/api
+
+## 命令行参数
+
+| 参数 | 说明 | 默认值 |
+|------|------|--------|
+| `--elements` | 元素列表 | `Cu Ag O Se` |
+| `--local` | 本地VASP目录 | — |
+| `--output` | 输出目录 | `phase_diagrams_output` |
+| `--eah` | E above hull 阈值 | `0.05` eV/atom |
+| `--compare-structure` | 启用结构对比 | `False` |
+| `--debug` | 调试模式 | `False` |
+
+## 许可证
+
+MIT License — 详见 [LICENSE](LICENSE)

chemphase-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+chemphase/__init__.py,sha256=p9VbMzSHeJ7-DtW7BD37OIvtHvgSQN92qH-G_Jr2-lQ,1150
+chemphase/__main__.py,sha256=4rL1MjgAJg4D9r8hlsuw07V9i3s1Tq9fhiJg_3z1Z0U,138
+chemphase/cli.py,sha256=wqu0ICrxFyBA-gy41ji-F77GwJitCaqL55PjHwN2MMA,7493
+chemphase/core.py,sha256=tloHRlBPta45vvA4rgGGrPy_HQzx55LCyG31Trep2YE,13331
+chemphase/diagrams.py,sha256=ebpLwlQb6x5BE-oVh6Gh8yBnQ7pLMgHLBB9D41JLC64,10742
+chemphase/plotting.py,sha256=vJYvCnj9t5uC7bUE2EZ4bYX7Pp-bqZ-8_pca_lsYI1Y,4088
+chemphase/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+chemphase-0.1.0.dist-info/licenses/LICENSE,sha256=1SF_moV1CtyB-g2v-Yo3V1_l5jVV0SN7CGjT_yWD0O0,1084
+chemphase-0.1.0.dist-info/METADATA,sha256=vSAioALKtA95jqeZ7C6KTaowvOsTEmew7PotYynDxys,3334
+chemphase-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+chemphase-0.1.0.dist-info/entry_points.txt,sha256=6Z2apB54PumucA2xQ9DuE0R4u0i7yYBZKjC6NC1JCBw,49
+chemphase-0.1.0.dist-info/top_level.txt,sha256=sqMrf27Atz_bzynj8ZzufVEXl_JtlldAdfy1ImMtSuc,10
+chemphase-0.1.0.dist-info/RECORD,,

chemphase-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

chemphase-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+chemphase = chemphase.cli:main

chemphase-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Phase Diagram Generator Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

chemphase-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+chemphase